Build secure, agentic workflows in TypeScript. Run them anywhere Node runs.

---

What is skelm?

skelm is a TypeScript framework for authoring and running workflows — typed orchestrations that mix deterministic code, LLM inference, and full agent loops behind a secure, default-deny execution model.

Key capabilities:

• TypeScript-native — Real .mts modules, no DSL or JSON config
• Default-deny security — Every permission must be explicitly declared
• Multi-backend agents — First-party agent, Pi, Opencode (native or ACP), Codex, Vercel AI, ACP (Copilot, Claude Code, Gemini), Anthropic, OpenAI
• Multimodal prompts — llm() and agent() accept image content parts; vision routed through vision-capable backends, denied at step start for the rest. Pair with ctx.artifacts to persist screenshots and other binary evidence on the run record
• MCP-native — Model Context Protocol servers lifecycle-managed by the gateway
• Skill support — Reusable SKILL.md capability bundles injected into agent system prompts; permission-gated via allowedSkills; auto-discovered from skills/**/SKILL.md by the gateway registry
• Trigger-rich runtime — Cron, intervals, and webhooks via @skelm/scheduler; poll, queue, file-watch, and event-source triggers via the gateway's TriggerCoordinator

Status: Early development. APIs are unstable until v1. Feedback and contributions welcome.

---

Quick start

# Install the CLI
npm install -g skelm

# Scaffold a project
skelm init my-bot && cd my-bot && npm install

# Run your first workflow
skelm run workflows/hello.workflow.mts --input '{"name":"world"}'

skelm run (and the other workflow / state commands) dispatch to a local gateway process. If none is running the CLI auto-starts one in the background; for a supervised service that survives reboots, install it with:

skelm gateway install --systemd   # linux
skelm gateway install --launchd   # macOS

skelm init scaffolds canonical .mts modules (skelm.config.mts and workflows/*.mts) so Node's native loader handles them regardless of package.json "type". From here you can edit workflows, add agent steps, schedule them, or stand up the gateway:

skelm schedule add workflows/hello.workflow.mts --cron '0 * * * *'  # cron job
skelm gateway start                                                # foreground (development)

📖 Next: Quickstart guide

---

Backend support

skelm supports multiple AI backends through pluggable adapters. Choose the one that fits your use case:

Backend	Package	Best for
First-party	@skelm/agent	OpenAI-compatible LLM, in-process permission enforcement, built-in tool surface, no external runtime dependency
Pi	@skelm/pi	Pi coding agent with full permission enforcement
Opencode	@skelm/opencode	Open-source coding agent backend (native; ACP transport also supported)
Codex	@skelm/codex	OpenAI Codex via the official @openai/codex-sdk — sandbox-aware (read-only / workspace-write), MCP + skills injection, streaming, thread resumption
Vercel AI	@skelm/vercel-ai	Vercel AI SDK with streaming support
ACP	Built-in	GitHub Copilot, Claude Code, Gemini via ACP (Opencode also available as native — see above)

See Backend documentation for setup guides, and Codex backend for OpenAI Codex specifically. Codex authenticates via the host codex CLI (codex login) or CODEX_API_KEY; skelm validates permissions at the boundary while Codex enforces its sandbox in-process.

---

Core concepts

Workflow step kinds

• code() — Deterministic logic, API calls, data transformation
• llm() — Single LLM inference call
• agent() — Multi-turn agent loops with tools, MCP, and skills

Control flow primitives

• parallel — Run steps concurrently
• forEach — Iterate over collections
• branch — Conditional execution
• loop — Repeat with exit conditions
• wait — Pause and resume later
• invoke — Call another pipeline by ID

Security model

• Default-deny permissions — Tools, MCP servers, network hosts, filesystem roots must be declared
• Network egress enforcement — Embedded CONNECT proxy blocks undeclared outbound connections
• Per-agent workspaces — Isolated filesystem roots prevent cross-step corruption
• Tamper-evident audit — Hash-chained decision journals for compliance

---

What you can build

• Coding assistants — Reachable on chat, open PRs in persistent workspaces
• Queue workers — Watch Jira, GitHub, or email and act on tickets
• Email triage — Classify, summarize, and journal decisions for audit
• Digest automation — Fan out, enrich with LLM, post to Slack
• HTTP webhooks — Typed workflows triggered by external events
• Research agents — Poll sources, store findings, resume after restart
• Compliance bots — Watch S3 buckets, run checks, escalate to agents
• UI automation — Vision LLM + screenshot artifacts; see the foundations recipe

📁 See examples/ for runnable starting points.

---

Package architecture

Package	Purpose
skelm	Meta-package — install this, re-exports @skelm/core + CLI
@skelm/core	Runtime, types, builders, permission model, event bus
@skelm/cli	CLI commands — run, schedule, gateway, audit
@skelm/gateway	Long-running orchestrator: HTTP, scheduler, agent lifecycle
@skelm/scheduler	Cron, interval, and webhook triggers (poll, queue, file-watch, event-source live in @skelm/gateway)
@skelm/integrations	Typed connectors for GitHub, Slack, Telegram
@skelm/integration-sdk	Authoring SDK for building custom skelm integrations
@skelm/pi	Pi coding-agent backend
@skelm/opencode	Opencode coding-agent backend
@skelm/codex	OpenAI Codex backend via the official @openai/codex-sdk
@skelm/vercel-ai	Vercel AI SDK backend with streaming
@skelm/agent	First-party native agent backend with built-in tools
@skelm/metrics	Prometheus-format metrics
@skelm/otel	OpenTelemetry tracing

---

Documentation

• Quickstart — Get started in 60 seconds
• Backends — Provider architecture and setup
• Guides — Testing, plugins, authoring patterns
• Recipes — Complete workflow examples
• Reference — CLI, HTTP API, OpenAPI spec
• Contributing — How to contribute

---

Community

• GitHub Discussions — Questions and show & tell
• Issues — Bug reports and feature requests
• Contributing — PRs welcome

---

License

MIT