<p align="center">
  <a href="https://loomcycle.dev"><img src="docs/assets/logo.png" alt="loomcycle" width="640" /></a>
</p>

<p align="center">
  <strong>The agentic runtime, in a sidecar.</strong><br/>
  <em>One Go binary alongside your application — hardened agent loop, MCP on both sides, multi-replica HA. Apache-2.0.</em>
</p>

<p align="center">
  🌐 <a href="https://loomcycle.dev"><strong>loomcycle.dev</strong></a> &nbsp;·&nbsp;
  📝 <a href="https://loomcycle.dev/blog/">Engineering blog</a> &nbsp;·&nbsp;
  📐 <a href="https://github.com/denn-gubsky/loomcycle/blob/main/docs/ARCHITECTURE.md">Architecture</a>
</p>

<p align="center">
  <a href="https://github.com/denn-gubsky/loomcycle/releases"><img alt="release" src="https://img.shields.io/github/v/tag/denn-gubsky/loomcycle?label=release"></a>
  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
  <img alt="go" src="https://img.shields.io/badge/go-1.22%2B-00ADD8">
  <a href="https://github.com/sponsors/denn-gubsky"><img alt="sponsor" src="https://img.shields.io/badge/sponsor-%E2%99%A5-ec4899"></a>
</p>

---

> 🌳 **Active development toward v1.0.** The core primitives stabilised through v0.8 → v0.16 — multi-replica HA, the substrate Defs (Agent/Skill/MCPServer/Schedule/Webhook/MemoryBackend), A2A interoperability, inbound webhooks, pluggable memory + a memory layer, and a synthetic code provider. The feature set is complete; a hardening + QA pass remains before the v1.0 tag. **OSS multi-tenant authorization** (per-principal bearer tokens) is the headline of **v1.1.0** — see "Planned" below. We welcome bug reports, security disclosures, feature contributions, downstream consumers, and forks. See [`CONTRIBUTING.md`](CONTRIBUTING.md).

---

## What it is

**The agentic runtime, in a sidecar.** loomcycle is one sub-40 MB Go binary that runs *alongside* your application — not inside it. Your app calls loomcycle over HTTP, gRPC, MCP, or via the TypeScript adapter; the agent loop, multi-provider routing, memory and channel primitives, MCP server identity, OpenTelemetry traces, and multi-replica coordination all live in the binary. It's the substrate your agents live on — and your application stays in whatever language you wrote it in.

**The shape that's different.** The agentic-systems market today gives you three choices — embed a Python or TypeScript library inside your process, rent a managed cloud service tied to one vendor's IAM, or proxy your model calls through a gateway that doesn't actually run agents. loomcycle is the fourth shape: a lightweight self-hostable runtime that owns the loop *and* speaks every wire format your stack already uses.

## What's shipped

| Capability | Released in |
|---|---|
| **Six providers, native HTTP, no vendor SDK** — Anthropic, OpenAI, DeepSeek, Gemini, Ollama cloud, Ollama local — behind one `Provider` interface with resolver-based routing per tier and effort | v0.4 → v0.8.x |
| **Nineteen built-in tools** including Claude Code parity (Read, Write, Edit, Grep, Glob, NotebookEdit), HTTP, WebFetch, WebSearch, Bash, Agent, Skill, Memory, Channel, AgentDef, SkillDef, Evaluation, Interruption, Context | v0.4 → v0.8.24 |
| **AgentDef + SkillDef + MCPServerDef substrate** — content-addressed by SHA-256, runtime-mutable, push-at-boot from your container image; verify-or-fork across deployments | v0.8.5 / v0.8.22 / v0.9.x |
| **Vector Memory** with semantic search — `embed: true` on writes, `op: search` on reads. sqlite-vec or pgvector; Voyage / OpenAI / Gemini / nomic-embed on the embedding side | v0.9.0 |
| **MCP on both sides** — loomcycle is both an MCP client (mounts external MCP servers as tools) and an MCP server (Claude Code and external orchestrators drive it via 21 meta-tools) | v0.8.15 |
| **OpenTelemetry** across loop + providers + tools + MCP — no transcripts in spans | v0.10.0 |
| **Per-tenant fairness** on the run-admitting semaphore (single-replica), cluster-wide (multi-replica) | v0.10.1 / v0.12.1 |
| **LLM Gateway + OpenAI-compatible shims** — `POST /v1/_llm/chat`, `POST /v1/chat/completions`, `POST /v1/embeddings`. Drop loomcycle in front of any LangChain / LlamaIndex / n8n / RAG pipeline that speaks OpenAI's wire format | v0.11.0 → v0.11.4 |
| **n8n community package** — `@loomcycle/n8n-nodes-loomcycle`. Five cluster sub-nodes, action nodes, two trigger nodes, six example workflows | v1.x (community) |
| **Anthropic MAX subscription OAuth for dev workflow** — reverse-engineered, dev-only, opt-in; see [`docs/PROVIDERS.md`](docs/PROVIDERS.md) | v0.11.10 |
| **Pause / Resume / Snapshot** — runtime-wide quiesce + cross-version-portable JSON snapshot. In-place upgrades, snapshot-based replica handoff | v0.8.17 → v0.8.18 |
| **Multi-replica HA** — Redis cancel pubsub, cross-replica run status, cluster-wide pause/resume + bus fanout, singleton sweepers, DB-backed session locks. Single binary scales from a cheap VPS to a multi-replica fleet | v0.12.0 → v0.12.5 |
| **UNIX-style trust model** — operator config is the floor; callers narrow per-request but never widen. Bearer auth at the HTTP frontier; sandbox (Posture A) vs operator-trusted (Posture B) selected via env | v0.4 → ongoing |
| **Embedded React Web UI** at `/ui` — Library admin (agents / skills / MCP servers), Activity Monitor, Channels view, audit log, **Schedules admin** | v0.8.21 → v0.12.7 |
| **Multi-replica HA capstone** — singleton sweepers, DB-backed session locks + hook registry, docs + hardening pass | v0.12.6 |
| **ScheduleDef substrate** — operator-yaml `scheduled_runs:` templates + dynamic per-user forks with versioning + lineage. Sweeper fires due rows in parallel; 5-op tool (`create`/`fork`/`get`/`list`/`retire`) + 2 hook ops (`add_hook`/`remove_hook`); `on_complete` delivery via `channel.publish` / `memory.set` / `mcp.call`. Full 4-transport CRUD + `/ui/schedules` admin tab | v0.12.7 |
| **Per-run named credentials** — `user_credentials: map<string,string>` on `POST /v1/runs` / gRPC / MCP / TS. `${run.credentials.<name>}` substitution in `mcp_servers.*.headers`. Back-compat: legacy `user_bearer` auto-promotes to `credentials.default` | v0.12.7 |
| **Bundled observability profiles** — three `docker compose up` stacks: Grafana+Tempo+Prom+Loki (open-source), Honeycomb (SaaS), Datadog APM. `GET /metrics` Prometheus endpoint | v0.12.7 |
| **Mock LLM provider** — cost-free 10K-agent stress harness. Variable latency + jitter + 429 / 5xx injection. Five model variants including `mock-mcp-caller` that exercises real MCP-tool dispatch end-to-end | v0.12.7 |
| **Curated MCP server recipe library** — bundled JSON templates (GitHub, Slack, Tavily, …) + `$LOOMCYCLE_MCP_RECIPES_ROOT` filesystem overlay + a 7-verb `loomcycle mcp-registry` CLI that copy-pastes a recipe into your `mcp_servers:` yaml | v0.12.8 |
| **Claude Code repo import** — `loomcycle import claude-code --from=./.claude/` walks agents / skills / mcp.json into loomcycle yaml (dry-run → review → `--write`); recipe-library rewrite, lossy-is-loud reporting. Paired with the `claude-code-plugin-loomcycle` Claude Code plugin (slash commands + skills + hooks over `loomcycle mcp`) | v0.12.8 |
| **Parent-context propagation** — opaque `parent_context` {root_agent_run_id, function_key, tier_at_run} on a run is inherited by every Agent-tool sub-agent, persisted, and echoed on the agent-status / run-state / SSE surfaces — so a consumer can attribute a child sub-agent's usage to the user-initiated request | v0.12.8 |
| **Tool-use hooks** — register HTTP webhooks against `(agent, tool, phase)` selectors via `POST /v1/hooks`. `pre` hooks rewrite a tool's input, deny it with a synthetic result, or (operator opt-in) widen hosts for one call; `post` hooks rewrite the result. Fail-open or fail-closed; narrows policy by default; DB-backed in cluster mode | v0.8.x → v0.12.5 |
| **A2A (Agent2Agent) interoperability** — loomcycle as an A2A **server** (well-known AgentCard + REST/JSON-RPC/gRPC bindings) and **client** (call remote peers as `a2a__<peer>__<skill>` tools). Two substrate Defs, signed cards (JWS/JCS), multi-tenant routing, `INPUT_REQUIRED` ↔ Interruption resume. Off by default | v0.13.0 |
| **Input webhooks** — `WebhookDef` substrate: external systems (GitHub/Stripe/Linear/CI/n8n) trigger agent runs or wake parked agents via signed `POST /v1/_webhooks/{name}`. HMAC-over-raw-body (verify-before-parse), strict JSONPath mapping, two-layer idempotency, per-Def rate limit, per-run credentials, `on_complete` hooks, admin triage. Off by default | v0.14.0 |
| **Memory ranking + pluggable backends** — `Memory.search` hybrid ranker (semantic + recency weights) + search-time dedup; `MemoryBackend` interface with in-process default + `MemoryBackendDef` substrate + Mem9 REST backend (per-agent `memory_backend` routing, tenancy + RFC-F creds + graceful fallback); `loomcycle memory-eval` scoring harness. Opt-in, zero-regression default | v0.15.0 |
| **Memory layer (add / recall)** — the `Memory` tool's optional LLM-extract paradigm: hand a backend conversation messages, it distils durable facts and answers natural-language recall (mem9 smart-mode). An optional capability alongside the frozen key/value `Backend`; the default in-process store fail-closes with `capability_unsupported` | v0.16.0 |
| **Synthetic `code-js` provider** — `provider: code-js` runs operator JavaScript (goja) as a first-class agent for deterministic glue at zero token cost; stateless **replay** execution (resumable across restart/replica, deterministic by construction); default-deny tools, off by default | v0.16.0 |

Full per-version log: [`REVISIONS.md`](REVISIONS.md).

## Two postures, one binary

Same Go binary, same config schema. Operator flips a few env vars to pick the posture.

| Posture | Configuration shape | Use case |
|---|---|---|
| **True managed sandbox** | `LOOMCYCLE_BASH_ENABLED=0`, `LOOMCYCLE_READ_ROOT` / `LOOMCYCLE_WRITE_ROOT` unset, `LOOMCYCLE_HTTP_HOST_ALLOWLIST` empty, `LOOMCYCLE_HTTP_CALLER_AUTHORITATIVE=1`. Every tool default-deny; agents can only reach what the caller's per-request `allowed_hosts` says. | Shared-server deployments processing untrusted prompts. The runtime survives contact with adversarial input. |
| **Agentic dev environment** | Bash enabled, filesystem roots set to your workspace, broad `allowed_hosts`, optional local Ollama for offline work. | Local development. Internal trusted operators. Single-user research workstation. |

The trust boundary is **operator/caller** — the operator config is the floor, callers can narrow per-request but never widen. The bearer token (`LOOMCYCLE_AUTH_TOKEN`) is the authority. Treat anyone with the token as fully trusted to drive the runtime. For true isolation in the sandbox posture, run loomcycle inside a container or VM — `Bash` is restricted (cwd, env scrub, output bounds, timeouts) but is **not** a kernel-level sandbox.

## Install

Pick the path that fits. All four ship the same single static binary
plus the v0.11.1 `init` / `doctor` first-run flow. `Context.help
installation` covers each in detail.

```sh
# Homebrew (macOS + Linux)
brew install denn-gubsky/loomcycle/loomcycle

# Docker (v0.11.2+; pull works on amd64 + arm64 including Apple Silicon)
docker pull denngubsky/loomcycle:latest

# go install from source (skips Web UI embedding — for dev only)
go install github.com/denn-gubsky/loomcycle/cmd/loomcycle@latest

# Direct tarball (one of darwin-arm64 / darwin-amd64 / linux-arm64 / linux-amd64)
curl -L https://github.com/denn-gubsky/loomcycle/releases/latest/download/loomcycle-darwin-arm64.tar.gz | tar xz
```

## Quick start

```sh
loomcycle init       # bootstrap ~/.config/loomcycle/loomcycle.yaml + README.md
# set $LOOMCYCLE_AUTH_TOKEN + at least one provider key in your shell rc
loomcycle doctor     # verify env + provider keys + storage + listen
loomcycle            # start the server on 127.0.0.1:8787

# Smoke
curl http://127.0.0.1:8787/healthz
# {"ok":true}

# Open the Web UI (one-time per browser session — sets HttpOnly cookie)
open "http://127.0.0.1:8787/ui?token=$LOOMCYCLE_AUTH_TOKEN"
```

Real call (from another terminal):

```sh
curl -N http://127.0.0.1:8787/v1/runs \
  -H "Authorization: Bearer $LOOMCYCLE_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"default","segments":[{"role":"user","content":[{"type":"trusted-text","text":"Hello"}]}]}'
```

Build from a checkout (for development):

```sh
make build-all       # UI + binary in one shot; output → ./bin/loomcycle
./bin/loomcycle --config loomcycle.example.yaml
```

**Multi-replica cluster demo (v0.12.x):** for a one-command `docker compose up` cluster (2 loomcycle replicas + Postgres + nginx LB) with a verify script, see [`examples/cluster/README.md`](examples/cluster/README.md). Full operator runbook in [`docs/MULTI-REPLICA.md`](docs/MULTI-REPLICA.md).

## Current and planned

**v0.16.0 — Memory layer + synthetic code provider.** The two capabilities that complete the substrate before the v1.0 hardening pass.

- **MemoryLayer (RFC K).** The `Memory` tool gains `add` / `recall` ops for LLM-extract memory products (mem9 smart-mode, mem0-style): you hand the backend conversation messages, it distils durable facts, and recall is a natural-language semantic search over them. It's an *optional* capability probed alongside the frozen flat key/value `Backend` (so every existing backend is untouched); the default in-process store is a key/value + vector store, **not** a memory layer, so it fail-closes `add`/`recall` with `capability_unsupported` rather than faking it. `add`/`recall` honor the agent's `memory_scopes` and the backend's tenancy prefix exactly like the key/value ops.
- **Synthetic `code-js` provider (RFC J).** An AgentDef with `provider: code-js` runs operator-authored JavaScript (via goja) instead of calling a model. From everywhere else in loomcycle it **is an agent** — same loop, OTEL spans, scheduler / webhook / A2A reachability, sub-agent composition, evaluation surface — at **zero token cost**, for the deterministic glue steps that don't need an LLM (ATS scrapes, known-shape SQL, format conversion, routing). Loop-driven dispatch (the provider only emits tool calls; the loop dispatches them with its hooks/OTEL/credentials). Stateless **replay** execution: each turn re-runs `run()` and replays the tool results recorded in the transcript, so the transcript is the durable state — a run is **resumable across restart / replica**, and ambient `Date.now()` / `Math.random()` are hooked so replay is deterministic by construction. Default-deny `allowed_tools` (a tool not granted simply isn't defined in JS); off by default behind `LOOMCYCLE_CODE_AGENTS_ENABLED=1` — operator-provided code runs in the operator's own trust posture.

**v0.15.0 — Memory ranking, dedup & pluggable backends (RFC I).** `Memory.search` gains a hybrid ranker (`semantic_weight·cos + recency_weight·decay + …`; default reproduces pure-cosine exactly) and optional search-time dedup of near-duplicate vectors. The storage path is refactored behind a `MemoryBackend` interface (in-process default + unconditional fallback) and a new **`MemoryBackendDef`** — the sixth substrate primitive — with full 4-transport CRUD; `AgentDef.memory_backend` routes a specific agent's memory to a named backend, including a **Mem9** REST backend (per-agent routing, tenancy + per-run creds + graceful fallback). New `loomcycle memory-eval` scoring harness. All opt-in, zero-regression.

**v0.14.0 / v0.14.1 — Input webhooks (RFC H).** A `WebhookDef` substrate so external systems (GitHub / Stripe / Linear / CI / n8n) trigger agent runs or wake parked agents via signed `POST /v1/_webhooks/{name}`: HMAC-over-raw-body (verify-before-parse), strict JSONPath request→run mapping, two-layer idempotency, per-Def rate limit, per-run credentials, `on_complete` hooks, and an admin triage surface. Off by default. (v0.14.1 is the first tagged cut of the v0.14 line — v0.14.0 was merged but never tagged independently — plus a docs correction.)

**Shipped before v0.14.0 (v0.4 → v0.13.x)** — the foundation and the substrate build-out:

- **Providers + loop:** six provider drivers (Anthropic, OpenAI, DeepSeek, Gemini, Ollama cloud + local) behind one `Provider` interface with resolver-based per-tier + effort routing and runtime fallback; the hardened model→tool_use→tool_result loop.
- **Tools + substrate:** the nineteen built-in tools (Claude Code parity — Read/Write/Edit/Grep/Glob/NotebookEdit — plus HTTP/WebFetch/WebSearch/Bash/Agent/Skill/Memory/Channel/Context/Interruption + the substrate Defs); the content-addressed, runtime-mutable **AgentDef / SkillDef / MCPServerDef / ScheduleDef** primitives (verify-or-fork across deployments); Vector Memory with semantic search (sqlite-vec / pgvector); **Channel** inter-agent bus; **Interruption** human-in-the-loop; tool-use **hooks**.
- **Interop:** MCP on both sides (client + the LoomCycle MCP server with meta-tools); the **LLM Gateway** + OpenAI-compatible chat/embeddings shims; **A2A (Agent2Agent)** server + client (v0.13.0); the `@loomcycle/n8n-nodes-loomcycle` community package; Anthropic MAX OAuth (dev-only).
- **Ops + HA:** OpenTelemetry across loop + providers + tools; per-tenant fairness; **Pause / Resume / Snapshot**; **multi-replica HA** (Redis cancel pubsub, cross-replica run status, DB-backed session locks, singleton sweepers); per-run named credentials; the embedded React Web UI (`/ui`); `loomcycle init` / `doctor`; Docker + Homebrew distribution.

Per-version detail for all of the above is in [`REVISIONS.md`](REVISIONS.md).

**Planned — v1.0 → v1.1.0:**

- **v1.0 — hardening + QA.** No new primitives: a security + robustness + runtime-QA pass across the v0.13–v0.16 surfaces (A2A, webhooks, pluggable memory + the memory layer, the code-js provider), then the **v1.0** tag. Ships with the existing single shared-token auth (`LOOMCYCLE_AUTH_TOKEN`) — right for single-operator and single-trusted-team deployments.
- **v1.1.0 (headline) — OSS multi-tenant authorization.** Replaces the single shared token with per-principal bearer tokens (token-per-developer/app, scopes, rotation, file audit), each bound to an **authoritative `(tenant, subject)`** resolved *from the token* — so per-subject fairness and per-tenant memory isolation become real (today they key on caller-asserted fields). Zero-disruption: `LOOMCYCLE_AUTH_TOKEN` keeps working; multi-tenancy is available, never required. Enterprise-grade auth (SSO / RBAC / SCIM / signed audit) is a separate edition.
- **Beyond** (polish): a settings UI, an operator cookbook of postures, broader distribution (Helm).

Full per-version release notes: [`REVISIONS.md`](REVISIONS.md).
Public roadmap with v0.8.x → v1.0 design details: [`docs/PLAN.md`](docs/PLAN.md).

## Architecture

Three diagrams cover different views of the same runtime:

<p align="center">
  <img src="docs/assets/architecture.png" alt="loomcycle architecture — clients at the top (app servers, CLIs, TS/Python SDKs, Claude Code & MCP orchestrators, LangChain/n8n via OpenAI-compat shim), the single Go binary in the middle (1..N replicas; five wire surfaces incl. HTTP+SSE / gRPC / Web UI / MCP server with 33 meta-tools / LLM Gateway → bearer auth + concurrency semaphore + per-user fairness → 36-method connector.Connector → agent loop → tool dispatcher with 19 built-in tools + MCP client transport + sub-agent runner → SQLite/Postgres store covering sessions, runs, events, memory, channels, substrate tables, replicas+user_quotas+runtime_state+hooks), OpenTelemetry sidecar emitting spans, and external services at the bottom (seven LLM providers including anthropic-oauth-dev, three embedders, external MCP servers cloud)" width="780" />
</p>

Diagram source: [`docs/architecture.d2`](docs/architecture.d2) (regenerate with `d2 docs/architecture.d2 docs/assets/architecture.png`).

**Connector detail** — the v0.8.15 `Connector` abstraction layer (the pink block in the middle of the main diagram) is the architectural anchor every wire transport dispatches through. The detail diagram enumerates all 36 methods + shows which transports IMPLEMENT, CONSUME, and MIRROR the interface:

<p align="center">
  <img src="docs/assets/architecture-connector.png" alt="connector.Connector interface with 36 methods grouped by domain (run lifecycle, agent registry, substrate tools, channel CRUD, pause/snapshot, hook registry) — HTTP server IMPLEMENTS as the canonical business logic, MCP and gRPC servers CONSUME via direct Go method dispatch, TypeScript and Python adapters MIRROR over the HTTP wire" width="780" />
</p>

Source: [`docs/architecture-connector.d2`](docs/architecture-connector.d2).

**Multi-replica cluster mode (v0.12.x)** — when `LOOMCYCLE_REPLICA_ID` is set per process and the Postgres backend is used, loomcycle runs as a cluster behind any HTTP load balancer. The shared Postgres doubles as the LISTEN/NOTIFY backplane for cross-replica cancel, pause/resume, run-state fanout, and quota notifications. SQLite refuses cluster mode at boot.

<p align="center">
  <img src="docs/assets/architecture-cluster.png" alt="multi-replica cluster deployment — clients hit an HTTP load balancer (nginx/Caddy/Traefik/HAProxy/ELB, SSE-friendly), which round-robins across N replicas each with a distinct LOOMCYCLE_REPLICA_ID + 30s heartbeat, all sharing a Postgres database that holds both the substrate tables (replicas, user_quotas, runs.replica_id, runtime_state, hooks added in v0.12.x) and the LISTEN/NOTIFY backplane carrying cancel/pause/runstate/channel/quota/hook topics, with singleton sweepers gated via pg_try_advisory_lock" width="780" />
</p>

Source: [`docs/architecture-cluster.d2`](docs/architecture-cluster.d2). Operator runbook: [`docs/MULTI-REPLICA.md`](docs/MULTI-REPLICA.md). Demo: [`examples/cluster/README.md`](examples/cluster/README.md).

Full request flow, abstractions, and concurrency model: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).

## Adapters

- **TypeScript** — `npm install @loomcycle/client` → see [`adapters/ts/`](adapters/ts/). HTTP+SSE.
- **Python** — `pip install loomcycle` → see [`adapters/python/`](adapters/python/). Async over `grpc.aio`.

## Security highlights

- **No vendor binary** in the loop. Pure HTTP to provider APIs. No subprocess auth inheritance.
- **Default-deny everything.** Every built-in tool is disabled until env-configured. Every agent gets zero tools until `allowed_tools` is set.
- **Two-layer policy + per-request narrowing.** Operator floor in env; agent narrowing in yaml; caller narrowing per-run. Caller can never widen.
- **SSRF defence.** Hostname allowlist + RFC1918/loopback/link-local IP block at the dial layer. Defeats DNS rebinding.
- **Constant-time bearer auth.** `sha256+CTC` on both HTTP and gRPC.
- **`Bash` is restricted, not isolated.** Run inside a container or VM if you need real isolation.

Full security model + the two-layer default-deny walkthrough: [`docs/TOOLS.md`](docs/TOOLS.md).

## Documentation

Repo-side docs (this directory):

- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — request flow, provider abstraction, agent loop, sub-agents, skills, storage, concurrency, cancellation.
- [`docs/TOOLS.md`](docs/TOOLS.md) — two-layer default-deny model, every built-in tool, MCP / LocalAPI integrations, per-request narrowing.
- [`docs/MCP_INTEGRATION.md`](docs/MCP_INTEGRATION.md) — end-to-end MCP HTTP pipeline: request lifecycle, `${run.user_bearer}` substitution, model-visibility boundary, recipe for wrapping a REST API as an MCP server consumable by loomcycle.
- [`docs/MCP_SERVER.md`](docs/MCP_SERVER.md) — register loomcycle as an MCP server in Claude Code / Claude Desktop: copy-paste config snippets for Docker / Homebrew / direct-binary transports + the `loomcycle mcp install` helper.
- [`docs/CLAUDE-CODE.md`](docs/CLAUDE-CODE.md) — driving loomcycle from Claude Code: the recommended `claude-code-plugin-loomcycle` plugin (slash commands + skills + hooks) vs. the manual `loomcycle mcp install` path.
- [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) — operator config guide: provider/tier/user_tier resolution rules, four cookbook patterns (single/multi-provider × single/multi-user-tier), `models:` alias map, and the agent `.md` frontmatter field reference.
- [`docs/POSTGRES.md`](docs/POSTGRES.md) — Postgres backend operator guide: configuration, migrations, sqlite→postgres runbook, concurrency benchmark.
- [`docs/GRPC.md`](docs/GRPC.md) — gRPC surface: enablement, wire-shape parity with HTTP+SSE, error mapping, Python adapter quick-start.
- [`docs/PLAN.md`](docs/PLAN.md) — public roadmap: shipped v0.4 → v0.8.12; planned v0.8.13 → v1.0.
- [`REVISIONS.md`](REVISIONS.md) — per-version release notes (v0.4.0 onward).
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution policy (closed for external PRs until v1.x).
- [`CLAUDE.md`](CLAUDE.md) — project guide for agents working in this repo (Claude Code).

In-binary docs (bundled `Context.help` topics — agents read these directly; operators hit `GET /v1/_help/<topic>` against a running instance):

- `installation` — all four install paths (Homebrew, Docker, `go install`, direct tarball) with verification + troubleshooting.
- `getting-started` — first-run walkthrough (`init` → set env vars → `doctor` → run).
- `llm-gateway` — direct LLM routing endpoint (v0.11.0; for n8n + LangChain consumers).
- `openai-compat` — drop-in OpenAI SDK shims (v0.11.3 chat + v0.11.4 embeddings) with Python + TypeScript examples.
- `fairness` — per-user concurrency quota policy.
- `observability` — OTEL trace export setup.
- `vector-memory`, `voyage-embedder`, `sqlite-vec` — Vector Memory backends.
- `dynamic-mcp` — register MCP servers at runtime.
- `bash-security` — Bash tool's restricted-not-isolated security posture.

Full list via `GET /v1/_help` against a running instance.

## Sponsor

If loomcycle is useful to you or your team, [GitHub Sponsors](https://github.com/sponsors/denn-gubsky) helps fund continued development. Individual supporters and corporate sponsors both welcome.

The runtime stays Apache-2.0 either way. Sponsorships directly fund the v0.12 → v1.0 runway: multi-replica HA, Helm chart, operator cookbook, settings UI, and the per-tier sustained engineering needed to keep the binary small and the substrate stable.

Current sponsors are listed in [`BACKERS.md`](BACKERS.md) (and at [loomcycle.dev/sponsors](https://loomcycle.dev/sponsors) with logos).

## License

Apache-2.0. See [LICENSE](LICENSE).
