# Loopstack

Loopstack is a TypeScript workflow framework for building stateful automations, AI agents, and interactive workflows on top of NestJS.

For the full documentation in a single file, see [llms-full.txt](https://loopstack.ai/llms-full.txt).

## Build

Step-by-step guides for building with Loopstack — getting started, workflow fundamentals, AI/LLM integration, workflow patterns, and third-party integrations.

- [Agent Workflows](https://loopstack.ai/llms/build/ai/agent-workflows.md): Building autonomous LLM agents that call tools in a loop. Covers the built-in AgentWorkflow module, custom agent loops with @Guard routing, error recovery, and max-iterations limits.
- [Chat Flows](https://loopstack.ai/llms/build/ai/chat-flows.md): Building multi-turn conversational workflows with LLMs using LlmMessageDocument, messagesSearchTag pattern, and wait transitions for user input.
- [LLM Providers](https://loopstack.ai/llms/build/ai/llm-providers.md): Using multiple LLM providers (Claude, OpenAI) through the runtime provider registry. Covers LlmProviderModule setup, provider selection per-call, and switching providers without code changes.
- [AI Structured Output](https://loopstack.ai/llms/build/ai/structured-output.md): Forcing LLMs to return structured JSON data using LlmGenerateObjectTool with Zod schemas. Provider-agnostic — works with Claude, OpenAI, and other providers.
- [AI Text Generation](https://loopstack.ai/llms/build/ai/text-generation.md): Calling LLMs for text generation using LlmGenerateTextTool. Covers setup, system prompts, message history, provider selection, prompt caching, and streaming.
- [AI Tool Calling](https://loopstack.ai/llms/build/ai/tool-calling.md): Enabling LLMs to invoke workflow tools via function calling. Covers LlmDelegateToolCallsTool, tool descriptions, passing tools to LLM calls, and handling tool results.
- [AI Token Usage Tracking](https://loopstack.ai/llms/build/ai/usage-tracking.md): Reading LlmUsage from LLM tool results. Every LLM tool (LlmGenerateTextTool, LlmGenerateObjectTool, document generation) returns LlmResultMeta with provider, model, and a usage breakdown — inputTokens, outputTokens, cacheCreationInputTokens, cacheReadInputTokens, reasoningTokens.
- [Creating Documents](https://loopstack.ai/llms/build/fundamentals/documents.md): How to define typed document classes with @Document() decorator, Zod validation schemas, and YAML widget configs for rendering in Loopstack Studio.
- [Modules & Workspaces](https://loopstack.ai/llms/build/fundamentals/modules.md): How to organize workflows, tools, and services into NestJS modules. Covers @StudioApp decorator for app identity, module structure, app modules vs feature modules, workspace configuration, forRoot/forFeature patterns, and provider registration.
- [Studio Configuration](https://loopstack.ai/llms/build/fundamentals/studio-config.md): Reference for the `ui` option on @StudioApp. Documents StudioUiConfig and the StudioWidgetConfig widget array used to customize an app's Studio surface.
- [Creating Tools](https://loopstack.ai/llms/build/fundamentals/tools.md): How to define custom tools with BaseTool, Zod argument schemas, @Tool() decorator, handle() method signature, tool configuration, and dependency injection into workflows.
- [Creating Workflows](https://loopstack.ai/llms/build/fundamentals/workflows.md): How to define workflow state machines using BaseWorkflow, @Workflow() decorator, @Transition() decorator, state typing, wait transitions, and guards. Includes full chat workflow example.
- [Getting Started](https://loopstack.ai/llms/build/getting-started.md): Step-by-step setup guide — install prerequisites, scaffold a NestJS app, add LoopstackModule, configure Docker Compose for PostgreSQL and Redis, and run your first workflow.
- [OAuth Authentication](https://loopstack.ai/llms/build/integrations/oauth.md): Integrating OAuth 2.0 authentication using @loopstack/oauth-module. Covers setup with Google Workspace provider, token management, and accessing OAuth-protected APIs from workflows.
- [Programmatic Workflow Execution](https://loopstack.ai/llms/build/integrations/programmatic-execution.md): Starting and managing workflows from code using WorkflowRunner. Covers triggering from API requests, webhooks, cron jobs, batch processing, and internal events.
- [Sandbox Execution](https://loopstack.ai/llms/build/integrations/sandbox.md): Executing untrusted code in Docker containers using @loopstack/sandbox-tool and @loopstack/sandbox-filesystem. Setup, file I/O inside sandboxes, and cleanup.
- [Secrets Management](https://loopstack.ai/llms/build/integrations/secrets.md): Requesting, storing, and retrieving secrets (API keys, tokens) at runtime using RequestSecretsTool, RequestSecretsTask, and GetSecretKeysTool from @loopstack/secrets-module.
- [Dynamic Routing](https://loopstack.ai/llms/build/patterns/dynamic-routing.md): Conditional workflow routing using @Guard decorators and priority-based transition selection when multiple transitions share the same source state.
- [Error Handling, Retry & Timeout](https://loopstack.ai/llms/build/patterns/error-handling.md): Recovering from transition errors with auto-retry and exponential backoff, custom error state transitions, manual retry via Studio UI, and transition timeouts.
- [Human-in-the-Loop](https://loopstack.ai/llms/build/patterns/human-in-the-loop.md): Pausing workflows for user input, review, or confirmation using wait:true transitions, document UI actions, payload schemas, and approval patterns.
- [State Management](https://loopstack.ai/llms/build/patterns/state-management.md): Defining, reading, and updating typed workflow state. Covers state interfaces, BaseWorkflow generics, state persistence across transitions, and state access patterns.
- [Sub-Workflows](https://loopstack.ai/llms/build/patterns/sub-workflows.md): Running workflows inside other workflows via .run(), the show option ('inline' | 'link' | 'hidden') for parent-view rendering, callback transitions, passing arguments to child workflows, and receiving sub-workflow results.
- [Template Expressions](https://loopstack.ai/llms/build/patterns/templates.md): Rendering dynamic text content with Handlebars templates via this.render(). Covers template syntax, variable interpolation, helpers, and use in prompts.
- [Troubleshooting](https://loopstack.ai/llms/build/troubleshooting.md): Solutions to common Loopstack setup and runtime issues — YAML assets missing at runtime, Studio not connecting to the backend, and wait transitions that never fire.

## Extend

How to add custom LLM providers and OAuth providers to the Loopstack registry.

- [Custom Bootstrap](https://loopstack.ai/llms/extend/custom-bootstrap.md): Advanced — replace LoopstackModule.forRoot() by wiring its underlying modules (ConfigModule, TypeOrmModule, EventEmitterModule, LoopCoreModule, LoopstackApiModule) yourself for granular control over database, config, and Nest bootstrap.
- [Studio Features](https://loopstack.ai/llms/extend/features.md): How Loopstack features (Git, File Explorer, Secrets, etc.) are registered, discovered, and surfaced in Studio. Covers the registerFeature() helper, forFeature() module pattern, and the backend → frontend feature flow.
- [Creating Custom LLM Providers](https://loopstack.ai/llms/extend/llm-providers.md): Implementing a new LLM provider by extending LlmProviderInterface and registering with LlmProviderRegistry. Covers the provider architecture, required methods, and module setup.
- [Creating Custom OAuth Providers](https://loopstack.ai/llms/extend/oauth-providers.md): Implementing a new OAuth provider by extending OAuthProviderInterface and registering with OAuthProviderRegistry. Covers required methods, token handling, and module setup.
- [Tool Interceptors](https://loopstack.ai/llms/extend/tool-interceptors.md): Advanced — register chain-based interceptors around every tool.call() for cross-cutting concerns (quota tracking, caching, structured logging, error handling). Covers the ToolInterceptor interface, @UseToolInterceptor() decorator, ToolExecutionContext, priority ordering, and the built-in ToolLoggingInterceptor.

## Reference

API and configuration reference — module options, environment variables, YAML schemas for workflows and documents, and import paths.

- [Configuration Reference](https://loopstack.ai/llms/reference/configuration.md): All LoopstackModule.forRoot() options and environment variables — database, Redis, authentication, CORS, and default settings.
- [Document YAML Schema](https://loopstack.ai/llms/reference/document-yaml.md): Complete reference for document .ui.yaml files — type, description, display components, and rendering configuration for Loopstack Studio.
- [Import Directory](https://loopstack.ai/llms/reference/imports.md): Quick-reference for all @loopstack/* import paths — workflows, tools, documents, LLM providers, OAuth, sandbox, secrets, and agent module exports.
- [Workflow YAML Schema](https://loopstack.ai/llms/reference/workflow-yaml.md): Complete reference for workflow .ui.yaml files — title, description, widget layout, input forms, action buttons, and enabled-state configuration for Loopstack Studio.

## Skills

- [Skill: Create a Custom Document](https://loopstack.ai/llms/skills/create-custom-document.md): Step-by-step instructions for AI agents to scaffold a new document — @Document decorator, Zod schema, YAML widget config, and how to save instances via documentStore.
- [Skill: Create a Custom Tool](https://loopstack.ai/llms/skills/create-custom-tool.md): Step-by-step instructions for AI agents to scaffold a new tool — BaseTool class, @Tool decorator, Zod argument schema, handle() method, and module registration.
- [Skill: Create a Custom Workflow](https://loopstack.ai/llms/skills/create-custom-workflow.md): Step-by-step instructions for AI agents to scaffold a new workflow — file structure, TypeScript class with @Workflow and @Transition decorators, YAML widget config, and module registration.
- [Skill: Use Core Tools](https://loopstack.ai/llms/skills/use-core-tools.md): Reference for AI agents on using built-in tools and documents from @loopstack/core and @loopstack/common — sub-workflow execution, document store, render, HTTP client, and core document types.
- [Skill: Use the Loopstack Registry](https://loopstack.ai/llms/skills/use-registry.md): Instructions for AI agents to discover, install, and integrate @loopstack/* registry packages — feature modules, tools, and example workflows.

## Registry

The Loopstack Registry — a curated collection of npm packages providing feature modules, standalone tools, and example workflows.

- [Registry Overview](https://loopstack.ai/llms/registry/index.md): The Loopstack Registry — a curated collection of npm packages providing feature modules (LLM, OAuth, Git, HITL), standalone tools (sandbox, filesystem), and example workflows. How to discover, install, and use @loopstack/* packages.

## Registry — Features

Official Loopstack modules providing LLM integrations, OAuth, human-in-the-loop, Git/GitHub tools, secrets management, and more.

- [Agent Module](https://loopstack.ai/llms/registry/features/agent-module.md): Generic LLM agent workflows for Loopstack — AgentWorkflow (single-run tool loop), ChatAgentWorkflow (multi-turn chat with optional task mode), AgentFinishTool, tool resolution via NestJS DI, configurable system prompt and tool set
- [Claude Module](https://loopstack.ai/llms/registry/features/claude-module.md): A collection of tools for performing AI actions using the Anthropic Claude API directly via the official SDK.
- [Claude Tools Module](https://loopstack.ai/llms/registry/features/claude-tools-module.md): Claude-specific tools that consume the LLM provider (e.g. web search using Claude server tools).
- [Code Agent Module](https://loopstack.ai/llms/registry/features/code-agent-module.md): AI-powered codebase exploration for Loopstack — ExploreTask tool launches AgentWorkflow sub-agent with glob/grep/read tools, CodeAgentModule registration, forFeature() LLM config, CallbackSchema for sub-workflow completion
- [Git Module](https://loopstack.ai/llms/registry/features/git-module.md): Git version control tools for Loopstack workflows — GitStatusTool,
- [GitHub Integration Module](https://loopstack.ai/llms/registry/features/github-integration-module.md): ConnectGitHubWorkflow — end-to-end guided workflow that authenticates via OAuth, creates or links a GitHub repo, configures git remotes, resolves branch divergence via HITL, and pushes. Uses GitHubIntegrationModule, OAuthWorkflow, AskUserWorkflow, git tools.
- [GitHub Module](https://loopstack.ai/llms/registry/features/github-module.md): GitHub OAuth provider and 25 API tools for Loopstack workflows — GitHubModule, GitHubOAuthProvider, OAuthProviderInterface, repositories, issues, pull requests, actions, content/git ops, search, users/orgs. Covers installation, tool args, auth pattern, and env vars.
- [Google Workspace Module](https://loopstack.ai/llms/registry/features/google-workspace-module.md): Google Calendar, Gmail, and Drive tools for Loopstack — 11 tools across 3 domains, Google OAuth provider, OAuthProviderInterface, token-based API access with automatic unauthorized error handling
- [Human-in-the-Loop Module](https://loopstack.ai/llms/registry/features/hitl-module.md): HITL workflows and tools for Loopstack — AskUserWorkflow (free-text, confirm, multiple-choice), ConfirmUserWorkflow (markdown review + confirm/deny), AskClarificationTool, AskForApprovalTool, document types for UI rendering
- [LLM Provider Module](https://loopstack.ai/llms/registry/features/llm-provider-module.md): Shared LLM provider contracts, registry, and helper services for the Loopstack automation framework. Provider modules (Claude, OpenAI, etc.) implement the LlmProviderInterface and register themselves at module init.
- [Local File Explorer Module](https://loopstack.ai/llms/registry/features/local-file-explorer-module.md): Loopstack registry feature exposing the local filesystem of a workspace as a REST API. LocalFileExplorerModule, LocalFileExplorerController endpoints for /files/tree and /files/read, FileApiService, FileSystemService, FileExplorerNodeDto, FileContentDto, path traversal protection, 10 MB file size limit, workflow YAML parsing.
- [MCP Module](https://loopstack.ai/llms/registry/features/mcp-module.md): Remote MCP client tools for Loopstack — McpModule.forRoot(), McpCallTool (mcp_call), McpListToolsTool (mcp_list_tools), McpToolConfig with allowedHosts, hostHeaderEnv, SSRF allowlist, Streamable HTTP and SSE transports, McpClientService, error hierarchy, McpMetricsPort
- [OAuth Module](https://loopstack.ai/llms/registry/features/oauth-module.md): Provider-agnostic OAuth 2.0 framework for Loopstack — OAuthModule, OAuthWorkflow, OAuthProviderRegistry, OAuthTokenStore, OAuthProviderInterface, BuildOAuthUrlTool, ExchangeOAuthTokenTool, OAuthPromptDocument, token storage with Redis fallback, pluggable provider interface, authorization code flow
- [OpenAI Module](https://loopstack.ai/llms/registry/features/openai-module.md): OpenAI LLM provider for the Loopstack automation framework. Implements LlmProviderInterface with the OpenAI SDK.
- [Quota Module](https://loopstack.ai/llms/registry/features/quota-module.md): Opt-in quota tracking and enforcement for Loopstack tool calls — QuotaModule.forRoot(), QuotaInterceptor, QuotaCalculatorRegistry, QuotaClientService, AiGenerateTextQuotaCalculator, ProcessingTimeQuotaCalculator, Redis-backed usage counters, model pricing lookup
- [Remote Client Module](https://loopstack.ai/llms/registry/features/remote-client-module.md): HTTP client and workflow tools for Loopstack remote servers — RemoteClientModule, RemoteClient service, EnvironmentService, ReadTool, WriteTool, EditTool, BashTool, GlobTool, GrepTool, RebuildAppTool, ResetWorkspaceTool, LogsTool, SyncSecretsTool, file operations, shell commands, environment management on remote workspaces
- [Remote File Explorer Module](https://loopstack.ai/llms/registry/features/remote-file-explorer-module.md): REST API controller for browsing files on remote Loopstack workspaces — RemoteFileExplorerModule, RemoteFileExplorerController, file tree and file content endpoints, proxies requests via RemoteClient and EnvironmentService
- [Secrets Module](https://loopstack.ai/llms/registry/features/secrets-module.md): Workspace-scoped secrets storage for Loopstack workflows — SecretEntity, SecretService, SecretController REST API, GetSecretKeysTool (get_secret_keys), RequestSecretsTool (request_secrets), RequestSecretsTask (request_secrets_task), SecretsRequestWorkflow, SecretRequestDocument. CRUD service, upsert, request secrets from users at runtime.
- [Web Module](https://loopstack.ai/llms/registry/features/web-module.md): Fetch and process web content. Converts HTML to Markdown, optionally summarizes against a prompt via Claude, with URL validation, same-origin redirect handling, LRU caching, and a preapproved-host allowlist.

## Registry — Examples

Example workflows demonstrating Loopstack patterns: chat, tool calling, agents, HITL, structured output, sub-workflows, and integrations.

- [Accessing Tool Results Example](https://loopstack.ai/llms/registry/examples/accessing-tool-results-example-workflow.md): Example workflow showing how to store and access data across workflow transitions using typed workflow state
- [Agent Example](https://loopstack.ai/llms/registry/examples/agent-example-workflow.md): Example launching AgentWorkflow as a sub-workflow with custom tools (weather_lookup, calculator) and rendering progress in Studio
- [Chat Example](https://loopstack.ai/llms/registry/examples/chat-example-workflow.md): Example workflow building an interactive chat interface — system prompt setup, wait transitions, LlmGenerateTextTool, message loop, prompt-input widget
- [Code Agent Example](https://loopstack.ai/llms/registry/examples/code-agent-example-workflow.md): Example launching ExploreAgentWorkflow as a sub-workflow to explore a remote workspace and surface a synthesized summary
- [Custom Tool Example](https://loopstack.ai/llms/registry/examples/custom-tool-example-module.md): Example implementing custom tools in a Loopstack workflow — BaseTool subclass, @Tool decorator, Zod schema, tool registration and injection
- [Delegate Error Handling Example](https://loopstack.ai/llms/registry/examples/delegate-error-example-workflow.md): Example showing how delegate tool-call loops handle failure modes — schema validation errors, runtime errors, failing sub-workflows, LLM error recovery
- [Dynamic Routing Example](https://loopstack.ai/llms/registry/examples/dynamic-routing-example-workflow.md): Example workflow implementing conditional routing based on runtime values using guards and transition priorities
- [Error Retry Example](https://loopstack.ai/llms/registry/examples/error-retry-example-workflow.md): Example demonstrating Loopstack retry and recovery — auto-retry, manual retry, custom error places, timeout handling, retry.place, hybrid retry patterns
- [Git Commit Flow Example](https://loopstack.ai/llms/registry/examples/git-commit-flow-example-workflow.md): Example of scripted multi-tool orchestration using git-module — GitStatusTool, GitAddTool, GitCommitTool, GitLogTool in sequence, no LLM
- [GitHub OAuth Example](https://loopstack.ai/llms/registry/examples/github-oauth-example.md): Example workflows using GitHub API with OAuth — structured repo overview and interactive Claude chat agent with 25 GitHub tools
- [Google OAuth Example](https://loopstack.ai/llms/registry/examples/google-oauth-example.md): Example workflows using Google Workspace APIs with OAuth — Calendar, Gmail, Drive, structured calendar summary and Claude chat agent with 11 Google tools
- [HITL Ask User Example](https://loopstack.ai/llms/registry/examples/hitl-ask-user-example-workflow.md): Example prompting the user for free-text input using AskUserWorkflow as a sub-workflow with callback, waiting on human input without blocking
- [HITL Confirm Example](https://loopstack.ai/llms/registry/examples/hitl-confirm-example-workflow.md): Example asking the user for yes/no confirmation using ConfirmUserWorkflow as a sub-workflow, branching on confirmed/denied outcome
- [LLM Multi-Provider Example](https://loopstack.ai/llms/registry/examples/llm-multi-provider-example-workflow.md): Example using multiple LLM providers (Claude and OpenAI) in the same workflow — side-by-side responses, call-time config with different provider settings
- [MCP Linear Example](https://loopstack.ai/llms/registry/examples/mcp-linear-example-workflow.md): Example connecting a Loopstack chat agent to Linear's hosted MCP server — mcp_list_tools, mcp_call, MCP tool config with allowedHosts
- [Meeting Notes Example](https://loopstack.ai/llms/registry/examples/meeting-notes-example-workflow.md): Example building a human-in-the-loop AI workflow — interactive documents, review steps, LLM-generated meeting notes with user approval
- [Module Config Example](https://loopstack.ai/llms/registry/examples/module-config-example.md): Example demonstrating configurable module patterns — forRoot + forFeature, per-module configuration isolation, shared GreeterTool
- [Prompt Example](https://loopstack.ai/llms/registry/examples/prompt-example-workflow.md): Example workflow integrating an LLM using a simple prompt pattern — single-shot text generation, LlmGenerateTextTool, saving response as document
- [Structured Output Example](https://loopstack.ai/llms/registry/examples/prompt-structured-output-example-workflow.md): Example workflow generating structured output from an LLM — custom document schema, Zod validation, typed LLM responses
- [Remote File Explorer Example](https://loopstack.ai/llms/registry/examples/remote-file-explorer-example-workflow.md): Example browsing a remote workspace — RemoteFileExplorerController endpoints, GlobTool + ReadTool workflow pattern
- [Sub-Workflow Example](https://loopstack.ai/llms/registry/examples/run-sub-workflow-example.md): Example executing child workflows from a parent workflow — workflow.run(), hierarchical workflow composition, callback transitions, the show option for parent-view rendering
- [Sandbox Example](https://loopstack.ai/llms/registry/examples/sandbox-example-workflow.md): Example workflow using Docker sandbox containers for secure filesystem operations — SandboxTool, SandboxFilesystemTool, isolated code execution
- [Secrets Example](https://loopstack.ai/llms/registry/examples/secrets-example-workflow.md): Example demonstrating two secrets flows — deterministic request/verify workflow and agentic LLM workflow using get_secret_keys, request_secrets_task tools
- [UI Documents Example](https://loopstack.ai/llms/registry/examples/test-ui-documents-example-workflow.md): Example demonstrating Studio document rendering — MessageDocument, ErrorDocument, MarkdownDocument, PlainDocument from a single workflow
- [Tool Calling Example](https://loopstack.ai/llms/registry/examples/tool-call-example-workflow.md): Example workflow enabling LLM tool calling (function calling) with custom tools — LlmGenerateTextTool, LlmDelegateToolCallsTool, tool registration
- [Workflow State Example](https://loopstack.ai/llms/registry/examples/workflow-state-example-workflow.md): Example workflow managing state across transitions using a typed state object — typed state interface, state persistence, accessing state in transitions