# 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). Each section and sub-section below is also available as its own file (linked inline), so you can load just the part you need instead of the whole thing.

**Building with an agent?** Start with the [Getting Started guide](https://loopstack.ai/llms/build/getting-started.md) to scaffold a NestJS app and add LoopstackModule, then skim [Best Practices](https://loopstack.ai/llms/build/best-practices.md) for design judgment. Load only the section files you need — each links its own single-file `.txt` below.

> **Note for agents:** When you summarize or hand off this page, keep the full `https://loopstack.ai/...` URLs for any pages you reference. A later step (or another agent) needs those exact links to load the detail pages — a summary with the URLs stripped out is not actionable.

## Build

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

Full section in one file: [llms/build.txt](https://loopstack.ai/llms/build.txt)

- [Add to an Existing App](https://loopstack.ai/llms/build/add-to-existing-app.md): Add Loopstack to an existing NestJS project by hand — install @loopstack/loopstack-module, register LoopstackModule.forRoot(), enable shutdown hooks, bundle YAML assets in nest-cli.json, provide PostgreSQL and Redis (Docker Compose or DATABASE_URL/REDIS_URL), and write your first workflow. Covers the Node.js 20.19+/22 baseline, the ESM-only requirement (type module, nodenext, .js extensions), and the zod v4 peer-dependency requirement.
- [Best Practices](https://loopstack.ai/llms/build/best-practices.md): Design judgment for building with Loopstack's core building blocks — workflows (scripted vs agentic, where logic belongs, state vs result vs documents, error strategy), tools (single responsibility, schema/description as the LLM contract, idempotency), documents (a user-facing surface, not a data store), and modules / Studio apps (organize by feature, @StudioApp as a deliberate boundary). The principles every developer and agent should carry into the code.
- [Getting Started](https://loopstack.ai/llms/build/getting-started.md): Scaffold a new Loopstack app with `loopstack create` — it generates a NestJS backend, a zero-config hello workflow, a Docker Compose file for PostgreSQL and Redis (plus an optional one for Studio), a ready-to-edit .env, and a CLAUDE.md. Then run your first workflow from the terminal with `loopstack run`, or point DATABASE_URL / REDIS_URL at your own instances.
- [Testing Methodology](https://loopstack.ai/llms/build/testing-methodology.md): How to turn acceptance criteria into an executable workflow test suite — criterion-named scenarios as the human-reviewable contract, the criteria matrix as a test-report query, three run modes (hermetic replay, live, record) from one spec via the fixture option, choosing check types by determinism class (mechanical, semantic, effectful, interactive), and completeness via coverage() and parkView() assertions. Conventions over framework code — works with plain vitest and @loopstack/testing.
- [Testing Workflows and Tools](https://loopstack.ai/llms/build/testing.md): How to test Loopstack workflows and tools — runWorkflow() in-process workflow tests with scripted HITL answers (queue() for cyclic workflows), provider overrides, contract-validated tool fakes (createContractFake) and tool mocks (createToolMock), state-machine coverage (coverage), trace diffing (diffTraces), park-view assertions (parkView — what the user would see at a park, shared rules with the CLI), and inline sub-workflows; testTool() unit tests; strict-sequence record/replay of tool responses (the fixture option with automatic record/replay and CI guard, record, the replayTools mock boundary, the --trace flag and LOOPSTACK_TRACE, loopstack runs --record --tools, replay()); live-LLM regression tests; and CI smoke runs with loopstack run --json. Covers @loopstack/testing, TestRun assertions (status, path, result, document, recordings, the run trace via trace and toolCalls), replay fixtures as ordered response scripts with metadata assertions, drift detection, resultSchema contract validation of replayed envelopes, replay boundaries (envelope-declared documents replay, pending envelopes, async tools always live), and the three strategies for scripting an async tool's answer.
- [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.

### Build / AI

Full sub-section in one file: [llms/build/ai.txt](https://loopstack.ai/llms/build/ai.txt)

- [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, switching providers without code changes, and which message history (meta.response, meta.provider, content blocks) and server tools carry over when a conversation switches provider.
- [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.

### Build / Fundamentals

Full sub-section in one file: [llms/build/fundamentals.txt](https://loopstack.ai/llms/build/fundamentals.txt)

- [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, the StudioWidgetConfig widget array, and the app-level start-form widget (options workflow, title, subtitle, label) that adds launch cards with a workflow's args form to the workspace home page.
- [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, resultSchema result contracts, 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. Covers the run trace — the per-run event journal (transitions, tool calls, documents, run.settled) with opt-in persistence via --trace. Includes full chat workflow example.

### Build / Integrations

Full sub-section in one file: [llms/build/integrations.txt](https://loopstack.ai/llms/build/integrations.txt)

- [Lifecycle Events](https://loopstack.ai/llms/build/integrations/lifecycle-events.md): In-process lifecycle events a host app listens to with @OnEvent from @nestjs/event-emitter — workflow.settled (WORKFLOW_SETTLED, WorkflowSettledEvent from @loopstack/core) when a run completes, fails or is canceled, and workflow.deleted / workspace.deleted when a run or workspace is deleted. Payload fields, when each event is emitted, the cascade rule for workspace and sub-workflow deletes, error handling, and why listeners must be idempotent.
- [OAuth Authentication](https://loopstack.ai/llms/build/integrations/oauth.md): Integrating OAuth 2.0 authentication using @loopstack/oauth. Covers setup with Google Workspace provider, token management, and accessing OAuth-protected APIs from workflows.
- [Scheduling & Programmatic Execution](https://loopstack.ai/llms/build/integrations/programmatic-execution.md): Scheduling and programmatic workflow execution with WorkflowRunner — cron (@Cron), webhook endpoints, delayed runs (SchedulerRegistry), batch fan-out, and triggering from API requests or internal events. run vs runSync, appName/userId context.
- [Sandbox Execution](https://loopstack.ai/llms/build/integrations/sandbox.md): Executing untrusted code in Docker containers using @loopstack/docker-sandbox and @loopstack/docker-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 SecretRequestDocument, RequestSecretsTask, and GetSecretKeysTool from @loopstack/secrets.

### Build / Patterns

Full sub-section in one file: [llms/build/patterns.txt](https://loopstack.ai/llms/build/patterns.txt)

- [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, retryTarget for retry-via-another-place, errorPlace routing for sync throws and sub-workflow failure callbacks, 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. Covers wait:true transitions on custom documents, AskUserWorkflow / ConfirmUserWorkflow sub-workflow shortcuts, and LLM-agent HITL via the ask_clarification and ask_for_approval tools.
- [State Management](https://loopstack.ai/llms/build/patterns/state-management.md): Defining, reading, and updating typed workflow state. Covers state interfaces, per-transition state typing, 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, typing the callback envelope via TransitionInput<TData>, handling sub-workflow failures via input.hasError / input.errorMessage without try/catch, passing arguments to child workflows, receiving sub-workflow results, and coordinating multiple sub-workflows via FanOutWorkflow (parallel) and SequenceWorkflow (sequential) with 'all' / 'allSettled' failure modes.
- [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.

## Extend

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

Full section in one file: [llms/extend.txt](https://loopstack.ai/llms/extend.txt)

- [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, replaying message history written by other providers (meta.response, meta.provider, toProviderMessage), rejecting unsupported server tools, 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 shipped interceptors (QuotaInterceptor, RecordToolInterceptor/ReplayToolInterceptor, TracingInterceptor example). Tool timing is recorded on the run trace, not in metadata.

## Reference

API and configuration reference — module options, environment variables, YAML schemas for workflows and documents, the prompt selection rules for waiting runs, and import paths.

Full section in one file: [llms/reference.txt](https://loopstack.ai/llms/reference.txt)

- [CLI Reference](https://loopstack.ai/llms/reference/cli.md): The loopstack CLI — scaffold a new app with loopstack create, run workflows from the terminal with live transition, LLM token, and tool call streaming, answer human-in-the-loop prompts inline (text, confirm, choices, forms with $EDITOR, chat inputs, secret entry) or non-interactively with loopstack answer, reattach to running or waiting runs with loopstack attach, retry failed runs interactively, inspect and watch runs, derive replay fixtures with runs --record, manage backend environments and API tokens. Covers loopstack create, list, run, runs (incl. pendingPrompt and --record), answer, attach, watch, login, env, the --json/--quiet output modes, exit codes for CI, stdin args (@-), --open, and LOOPSTACK_URL/LOOPSTACK_TOKEN/LOOPSTACK_STUDIO_URL configuration.
- [TypeScript SDK (@loopstack/client)](https://loopstack.ai/llms/reference/client.md): The headless TypeScript SDK for Loopstack — createClient, typed resources (workflows, documents, processor, workspaces, config, dashboard, auth), the SSE event stream (stream.on, stream.events async iterator), token and cookie authentication, query descriptors for TanStack Query, and a complete bare-Node example that starts a workflow run and streams it to completion.
- [Configuration Reference](https://loopstack.ai/llms/reference/configuration.md): All LoopstackModule.forRoot() options and environment variables — database, Redis, authentication, CORS (cors, corsOrigins / CORS_ORIGINS / FRONTEND_URL allowlist), event stream tuning (sse.bufferSize / bufferTtlMs / heartbeatIntervalMs), run trace persistence (trace / LOOPSTACK_TRACE), API list page sizes (*_DEFAULT_LIMIT, DOCUMENT_MAX_LIMIT), scheduler concurrency (TASK_CONCURRENCY), graceful shutdown deadline (SHUTDOWN_DRAIN_TIMEOUT_MS), LLM provider keys and models (CLAUDE_MODEL, OPENAI_MODEL), registry package settings (WORKSPACE_BASE_PATH, CLAUDE_WEB_FETCH_MODEL, QUOTA_*), 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.
- [Prompt Selection Rules](https://loopstack.ai/llms/reference/prompt-selection.md): How Studio, the CLI and TestRun.parkView() decide which prompt a waiting run shows — the shared @loopstack/contracts/park-view rules. Covers answerable states, run-tree order, evaluateWorkflowPrompts candidate order (documents before workflow widgets), DISPLAY_WIDGETS, internal/hideAtPlaces/enableAtPlaces, answered documents, widgetState with showWhen/enabledWhen, resolveSubmitTransition and the lone-transition rule, pickPrompt prompt/blocked/fallback, and the toParkView result.
- [React Hooks (@loopstack/react)](https://loopstack.ai/llms/reference/react.md): React adapter for the Loopstack SDK — LoopstackProvider, TanStack Query hooks (useWorkflow, useWorkflowList, useWorkflowDocuments, useWorkspaceList, useAppsConfig, useDashboardStats, useMe and more), mutations (useStartWorkflow, useRunWorkflow, workspace CRUD), useLiveInvalidation for SSE-driven cache refresh, and useLlmStream for live LLM token streaming.
- [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 place-based widget gating with enabledWhen (disable) and showWhen (hide) for Loopstack Studio.

### Reference / API

Full sub-section in one file: [llms/reference/api.txt](https://loopstack.ai/llms/reference/api.txt)

- [API: @loopstack/agent](https://loopstack.ai/llms/reference/api/agent.md): Public API reference for @loopstack/agent
- [API: @loopstack/claude-tools](https://loopstack.ai/llms/reference/api/claude-tools.md): Public API reference for @loopstack/claude-tools
- [API: @loopstack/claude](https://loopstack.ai/llms/reference/api/claude.md): Public API reference for @loopstack/claude
- [API: @loopstack/code-agent](https://loopstack.ai/llms/reference/api/code-agent.md): Public API reference for @loopstack/code-agent
- [API: @loopstack/common](https://loopstack.ai/llms/reference/api/common.md): Public API reference for @loopstack/common
- [API: @loopstack/core](https://loopstack.ai/llms/reference/api/core.md): Public API reference for @loopstack/core
- [API: @loopstack/docker-sandbox-filesystem](https://loopstack.ai/llms/reference/api/docker-sandbox-filesystem.md): Public API reference for @loopstack/docker-sandbox-filesystem
- [API: @loopstack/docker-sandbox](https://loopstack.ai/llms/reference/api/docker-sandbox.md): Public API reference for @loopstack/docker-sandbox
- [API: @loopstack/git](https://loopstack.ai/llms/reference/api/git.md): Public API reference for @loopstack/git
- [API: @loopstack/github-integration](https://loopstack.ai/llms/reference/api/github-integration.md): Public API reference for @loopstack/github-integration
- [API: @loopstack/github](https://loopstack.ai/llms/reference/api/github.md): Public API reference for @loopstack/github
- [API: @loopstack/google-workspace](https://loopstack.ai/llms/reference/api/google-workspace.md): Public API reference for @loopstack/google-workspace
- [API: @loopstack/hitl](https://loopstack.ai/llms/reference/api/hitl.md): Public API reference for @loopstack/hitl
- [API: @loopstack/llm-provider](https://loopstack.ai/llms/reference/api/llm-provider.md): Public API reference for @loopstack/llm-provider
- [API: @loopstack/local-file-explorer](https://loopstack.ai/llms/reference/api/local-file-explorer.md): Public API reference for @loopstack/local-file-explorer
- [API: @loopstack/mcp](https://loopstack.ai/llms/reference/api/mcp.md): Public API reference for @loopstack/mcp
- [API: @loopstack/oauth](https://loopstack.ai/llms/reference/api/oauth.md): Public API reference for @loopstack/oauth
- [API: @loopstack/openai](https://loopstack.ai/llms/reference/api/openai.md): Public API reference for @loopstack/openai
- [API: @loopstack/quota](https://loopstack.ai/llms/reference/api/quota.md): Public API reference for @loopstack/quota
- [API: @loopstack/remote-client](https://loopstack.ai/llms/reference/api/remote-client.md): Public API reference for @loopstack/remote-client
- [API: @loopstack/remote-file-explorer](https://loopstack.ai/llms/reference/api/remote-file-explorer.md): Public API reference for @loopstack/remote-file-explorer
- [API: @loopstack/secrets](https://loopstack.ai/llms/reference/api/secrets.md): Public API reference for @loopstack/secrets
- [API: @loopstack/web](https://loopstack.ai/llms/reference/api/web.md): Public API reference for @loopstack/web

## Skills

Full section in one file: [llms/skills.txt](https://loopstack.ai/llms/skills.txt)

- [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 via npm, and to read and copy example workflows from the examples app.

## Registry

The Loopstack Registry — a curated collection of npm packages providing LLM providers, agents, tools, OAuth integrations, workspace runtime and Studio surfaces.

Full section in one file: [llms/registry.txt](https://loopstack.ai/llms/registry.txt)

- [Registry Overview](https://loopstack.ai/llms/registry/index.md): The Loopstack Registry — a curated collection of @loopstack/* npm packages grouped by what they add (LLM providers, agents and HITL, tools, OAuth providers and integrations, workspaces and runtime, Studio surfaces). How to discover, install, and inspect registry packages.

## Registry — Packages

Official Loopstack packages providing LLM providers, OAuth, human-in-the-loop, Git/GitHub tools, Docker sandboxes, secrets management, and more.

Full section in one file: [llms/registry/packages.txt](https://loopstack.ai/llms/registry/packages.txt)

- [Agent Module](https://loopstack.ai/llms/registry/packages/agent.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
- [Claims Module](https://loopstack.ai/llms/registry/packages/claims.md): @loopstack/claims — resource claims for Loopstack workflows. Exclusive and pooled resources claimed by a run or a workspace, released when their scope ends. Covers mutex, pool-of-N and reader/writer lock patterns with ClaimsModule, the claim tools and run/workspace claim scopes.
- [Claude Module](https://loopstack.ai/llms/registry/packages/claude.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/packages/claude-tools.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/packages/code-agent.md): AI-powered codebase exploration for Loopstack — ExploreTask tool launches AgentWorkflow sub-agent with glob/grep/read tools, CodeAgentModule registration, forFeature() LLM config, TransitionInput envelope for sub-workflow completion
- [Code Workspace Module](https://loopstack.ai/llms/registry/packages/code-workspace.md): @loopstack/code-workspace — one checkout per workspace from shared generational bases, worked in disposable Docker containers. Provisioning, inventory and reclamation of repos, checkouts, containers and volumes with CodeWorkspaceModule and CodeWorkspaceMaintenanceModule.
- [Sandbox Tool](https://loopstack.ai/llms/registry/packages/docker-sandbox.md): Docker sandbox tool for Loopstack — SandboxToolModule, SandboxInit, SandboxCommand, SandboxDestroy tools, DockerContainerManagerService. Create isolated Docker containers, execute commands, manage container lifecycle in workflows.
- [Sandbox Filesystem](https://loopstack.ai/llms/registry/packages/docker-sandbox-filesystem.md): SandboxFilesystemModule providing SandboxWriteFile, SandboxReadFile, SandboxListDirectory, SandboxCreateDirectory, SandboxDelete, SandboxExists, SandboxFileInfo tools for secure file operations inside Docker containers. Depends on @loopstack/docker-sandbox.
- [Git Module](https://loopstack.ai/llms/registry/packages/git.md): Git version control tools for Loopstack workflows — GitStatusTool,
- [GitHub Module](https://loopstack.ai/llms/registry/packages/github.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.
- [GitHub Integration Module](https://loopstack.ai/llms/registry/packages/github-integration.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.
- [Google Workspace Module](https://loopstack.ai/llms/registry/packages/google-workspace.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
- [Handoff Module](https://loopstack.ai/llms/registry/packages/handoff.md): Hand-offs from a Loopstack run to the user's machine — HandoffModule.forFeature() lights up the Studio Handoff panel; HandoffDocument (copy-a-command or open-a-URL card), ChangedFilesDocument (changed-file tree with Zed / VS Code / file-explorer actions) and TerminalHandoffDocument (CLI terminal-handoff widget).
- [Human-in-the-Loop Module](https://loopstack.ai/llms/registry/packages/hitl.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/packages/llm-provider.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/packages/local-file-explorer.md): Loopstack registry package exposing the local filesystem of a workspace as a REST API. LocalFileExplorerModule, LocalFileExplorerController endpoints for /local-files/tree and /local-files/read, FileApiService, FileSystemService, FileExplorerNodeDto, FileContentDto, path traversal protection, 10 MB file size limit, workflow YAML parsing.
- [MCP Module](https://loopstack.ai/llms/registry/packages/mcp.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/packages/oauth.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/packages/openai.md): OpenAI LLM provider for the Loopstack automation framework. Implements LlmProviderInterface with the OpenAI SDK.
- [Quota Module](https://loopstack.ai/llms/registry/packages/quota.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/packages/remote-client.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/packages/remote-file-explorer.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/packages/secrets.md): Workspace-scoped secrets storage for Loopstack workflows — SecretEntity, SecretService, SecretController REST API, GetSecretKeysTool (get_secret_keys), RequestSecretsTask (request_secrets_task), SecretsRequestWorkflow, SecretRequestDocument. CRUD service, upsert, request secrets from users at runtime.
- [TypeSafe Module](https://loopstack.ai/llms/registry/packages/typesafe.md): Typed decisions and classifications with TypeSafe AI. Ask yes/no, choice and score questions about any state from a workflow or agent and get probabilities back.
- [Web Module](https://loopstack.ai/llms/registry/packages/web.md): Fetch and process web content. Converts HTML to Markdown, optionally summarizes against a prompt via the configured LLM provider, with URL validation, same-origin redirect handling, LRU caching, and a preapproved-host allowlist.

## Examples

Example workflows demonstrating Loopstack patterns: chat, tool calling, agents, HITL, structured output, sub-workflows, and integrations. One runnable app, one module per theme.

Full section in one file: [llms/examples.txt](https://loopstack.ai/llms/examples.txt)

- [Advanced Workflows Examples](https://loopstack.ai/llms/examples/advanced-workflows.md): In-depth examples of advanced Loopstack workflow patterns — state, dynamic routing, sub-workflows (parent, fan-out, sequence, show modes, error handling), batch processing, custom tools, configurable modules, and built-in UI documents.
- [Agent Examples](https://loopstack.ai/llms/examples/agent.md): Workflow examples for LLM agents in Loopstack — basic AgentWorkflow with custom tools, tool errors fed back to the LLM, code-exploration agent, and a from-scratch custom agent loop with a turn budget.
- [Error Handling Examples](https://loopstack.ai/llms/examples/error-handling.md): Error handling workflow examples for Loopstack — auto-retry with exponential backoff, retryTarget, errorPlace recovery, manual retry, transition timeouts, and sub-workflow failures routed via errorPlace.
- [Git Examples](https://loopstack.ai/llms/examples/git.md): Git and GitHub workflow examples — scripted multi-tool git operations and end-to-end repo sync via ConnectGitHubWorkflow
- [GitHub Examples](https://loopstack.ai/llms/examples/github.md): GitHub integration workflow examples for Loopstack — a scripted repo overview that walks the GitHub read tools, and an interactive Claude agent with 25 GitHub tools. Both sign in through the OAuth sub-workflow when a tool reports unauthorized.
- [Google Workspace Examples](https://loopstack.ai/llms/examples/google-workspace.md): Google Workspace integration workflow examples for Loopstack — a scripted Google Calendar summary, and an interactive Claude agent with Calendar, Gmail and Drive tools. Both sign in through the OAuth sub-workflow when a tool reports unauthorized.
- [HITL Examples](https://loopstack.ai/llms/examples/hitl.md): Workflow examples for Human-in-the-Loop patterns in Loopstack — custom Document with a form widget, AskUserWorkflow / ConfirmUserWorkflow sub-workflow shortcuts, LLM agent loops with ask_clarification / ask_for_approval, and an end-to-end meeting-notes review flow.
- [Integration Examples (placeholder)](https://loopstack.ai/llms/examples/integrations.md): Placeholder for integration / notification workflow examples in Loopstack — Slack, email, generic HTTP webhook fire-and-forget (coming soon)
- [LLM Examples](https://loopstack.ai/llms/examples/llm.md): Workflow examples for LLM integration in Loopstack — simple prompts, structured output with Zod schemas, multi-provider comparison, web fetch with summarization
- [Local File Explorer Examples](https://loopstack.ai/llms/examples/local-file-explorer.md): Local file explorer workflow example for Loopstack — build a file tree of the workspace with FileSystemService from @loopstack/local-file-explorer.
- [MCP Examples](https://loopstack.ai/llms/examples/mcp.md): Workflow example for remote MCP servers in Loopstack — McpModule.forRoot with an allowedHosts allowlist and a hostHeaderEnv auth header mapping, and a chat agent that uses the mcp_list_tools and mcp_call tools against Linear's hosted MCP server.
- [Observability Examples](https://loopstack.ai/llms/examples/observability.md): Workflow examples for observability in Loopstack — quota tracking, custom tool interceptors for tracing, custom quota calculators, event-driven audit logging, and reading a run's checkpoint history with client.workflows.checkpoints and loopstack runs
- [Remote Client Examples](https://loopstack.ai/llms/examples/remote-client.md): Remote agent workflow examples for Loopstack — run shell commands and edit files on a remote workspace, and search its files, with the @loopstack/remote-client tools; plus the Remote Files panel from @loopstack/remote-file-explorer.
- [Sandbox Examples](https://loopstack.ai/llms/examples/sandbox.md): Docker sandbox workflow example for Loopstack — init a container, run file operations inside it with the sandbox filesystem tools, and destroy it.
- [Scheduling Examples](https://loopstack.ai/llms/examples/scheduling.md): Runnable Loopstack examples for the scheduling fundamentals — cron (@Cron), webhook (@Post + @Public controller), delayed runs (SchedulerRegistry timeout), and batch (Promise.all fan-out). Each trigger starts a workflow with WorkflowRunner.run.
- [Secrets Examples](https://loopstack.ai/llms/examples/secrets.md): Workflow examples for secrets management in Loopstack — deterministic request/verify flow and a chat agent using the get_secret_keys and request_secrets_task tools
- [Testing Examples](https://loopstack.ai/llms/examples/testing.md): Runnable workflow-testing examples for Loopstack — runWorkflow() in-process workflow tests with scripted HITL answers, parkView() park assertions, coverage() gates, testTool() tool unit tests, fixture auto record/replay, and createContractFake() DI fakes. Companion package to the Testing guide.