patchcord

module

v0.1.2 Latest Latest Go to latest Published: Aug 5, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/lucasglmt/patchcord

Links

Open Source Insights

README ¶

Patchcord

The extensible runtime for integrations, workflows and intelligent apps. Connect anything. Automate everything. Build on top.

Patchcord is a local-first, universal execution agent written in Go. It loads and supervises independent plugins, manages connectors, executes atomic actions, and orchestrates versioned, declarative workflows — while exposing a stable public API consumed by a CLI, a TypeScript SDK, and third-party applications.

Patchcord Agent is the fundamental product. Plugins provide capabilities. Workflows provide orchestration. Applications provide the experience.

Status

Early stage — Phase 1 (Core minimal) of the roadmap. No stable release yet. See docs/PATCHCORD_VISION_ARCHITECTURE.md for the full product and architecture vision, and docs/adr/ for the architecture decision records.

Installing

Prebuilt binaries for linux/darwin/windows (amd64/arm64) are attached to every GitHub Release.

# macOS, or Linux via Linuxbrew
brew install lucasGlmt/patchcord/patchcord

# Debian/Ubuntu — download the .deb from the release page, then
sudo dpkg -i patchcord_*_linux_amd64.deb

# Fedora/RHEL — download the .rpm from the release page, then
sudo rpm -i patchcord_*_linux_amd64.rpm

There is deliberately no hosted apt/dnf repository or Chocolatey package — see ADR-0057 for why.

macOS: the binary isn't code-signed (no Apple Developer ID — see ADR-0057), so Gatekeeper blocks the first run of a brew-installed or directly downloaded copy (patchcord: rejected / the process just dies). Clear the quarantine flag once, after installing:

xattr -d com.apple.quarantine "$(which patchcord)"

Repository layout

This is a monorepo, with boundaries treated as if each component already lived in its own repository:

cmd/patchcord/     entry point of the main binary
internal/          core runtime — never imported by plugins/, sdk/, or apps/
api/               public contracts (OpenAPI/Protobuf) for the agent, plugin
                   protocol, workflow format, and app manifests
sdk/go-plugin/     official Go SDK for writing a plugin
sdk/typescript/    official TypeScript SDK for building applications
plugins/examples/  example plugins
apps/examples/     example applications
docs/              vision document and architecture decision records
migrations/        database schema migrations

Non-negotiables

The core never imports a concrete business integration (no Gmail, OpenAI, Postgres driver, etc. inside internal/) — capabilities arrive only through the plugin protocol.
A plugin depends only on the public protocol and sdk/go-plugin — never on internal/.
Public boundaries (client API, plugin protocol, package/workflow formats) are versioned contracts (Protobuf / JSON Schema / OpenAPI).
The CLI, applications, and dashboards all call the same internal services as the public API — never duplicated logic.
The cloud is always optional; no core feature requires a remote account.

See CLAUDE.md for the full set of contribution rules.

Building

go build ./...
go vet ./...
go test ./...

make build/make build-all embed a version into the binary (see Versioning below); a plain go build falls back to dev.

Versioning

Patchcord follows SemVer (vX.Y.Z); pre-1.0, any 0.x bump may contain breaking changes. patchcord version prints the binary's version, commit and build date; patchcord --version prints the short form; GET /v1/system/health reports it as version for running instances.

Releases are cut by pushing a vX.Y.Z tag: make changelog regenerates CHANGELOG.md from Conventional Commits, then git tag vX.Y.Z && git push --tags hands off to CI (.github/workflows/release.yml), which cross-compiles and publishes a GitHub Release via goreleaser. See ADR-0056 for the full decision.

License

Apache License 2.0 — see LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api
agent Package agent holds the agent's public HTTP API contract: the OpenAPI (Swagger 2.0) specification generated from internal/api's swag annotations.	Package agent holds the agent's public HTTP API contract: the OpenAPI (Swagger 2.0) specification generated from internal/api's swag annotations.
app Package app holds the public contract for the application package format: the JSON Schema of patchcord-app.yaml (vision doc §7.6, §9.3, §15.4).	Package app holds the public contract for the application package format: the JSON Schema of patchcord-app.yaml (vision doc §7.6, §9.3, §15.4).
plugin/v1
plugin module
cmd
patchcord command Command patchcord is the entry point of the Patchcord agent binary.	Command patchcord is the entry point of the Patchcord agent binary.
internal
api General API metadata swag (`make swagger`) reads to generate the OpenAPI spec committed at api/agent/openapi.json — see that package's doc comment.	General API metadata swag (`make swagger`) reads to generate the OpenAPI spec committed at api/agent/openapi.json — see that package's doc comment.
apps Package apps manages installed applications: web frontends built on top of the agent's public API (vision document, section 7.6).	Package apps manages installed applications: web frontends built on top of the agent's public API (vision document, section 7.6).
auth Package auth issues and validates the "limited sessions" an installed application receives (vision document, section 15.4): a session is scoped to exactly the permissions its application's manifest declares and never carries the rest of the public API's default access.	Package auth issues and validates the "limited sessions" an installed application receives (vision document, section 15.4): a session is scoped to exactly the permissions its application's manifest declares and never carries the rest of the public API's default access.
bundles Package bundles installs bundles: packages that group an application, its workflows, and its plugin dependencies into one .patchcord-bundle archive (vision document, section 9.3).	Package bundles installs bundles: packages that group an application, its workflows, and its plugin dependencies into one .patchcord-bundle archive (vision document, section 9.3).
cli Package cli defines the Patchcord command-line interface.	Package cli defines the Patchcord command-line interface.
config Package config loads the settings `patchcord serve` runs with from three layered sources — a YAML file, environment variables, and CLI flags — in that increasing order of precedence: a flag explicitly passed always wins, then an environment variable, then the config file, then a built-in default (ADR-0038).	Package config loads the settings `patchcord serve` runs with from three layered sources — a YAML file, environment variables, and CLI flags — in that increasing order of precedence: a flag explicitly passed always wins, then an environment variable, then the config file, then a built-in default (ADR-0038).
connectors Package connectors manages connector instances: persistent, named configurations for accessing an external system (vision document, section 7.3).	Package connectors manages connector instances: persistent, named configurations for accessing an external system (vision document, section 7.3).
packaging Package packaging holds the tar.gz archive primitives shared by every installable Patchcord package format (.patchcord-app, .patchcord-plugin, .patchcord-bundle): archiving a validated source directory, and safely extracting an untrusted archive back onto disk.	Package packaging holds the tar.gz archive primitives shared by every installable Patchcord package format (.patchcord-app, .patchcord-plugin, .patchcord-bundle): archiving a validated source directory, and safely extracting an untrusted archive back onto disk.
persistence Package persistence manages the agent's SQLite database: opening it with the pragmas Patchcord relies on, and applying versioned migrations.	Package persistence manages the agent's SQLite database: opening it with the pragmas Patchcord relies on, and applying versioned migrations.
plugins Package plugins launches Patchcord plugin processes and performs the protocol handshake described in the vision document (section 8.3).	Package plugins launches Patchcord plugin processes and performs the protocol handshake described in the vision document (section 8.3).
plugins/embedded Package embedded holds Patchcord's bundled reference plugins — text, json, encoding, http and time (plugins/examples/*, chosen because none of them has a concrete external service behind it) — as prebuilt executables embedded straight into the patchcord binary for the platform it was built for.	Package embedded holds Patchcord's bundled reference plugins — text, json, encoding, http and time (plugins/examples/*, chosen because none of them has a concrete external service behind it) — as prebuilt executables embedded straight into the patchcord binary for the platform it was built for.
registry Package registry resolves a package id (optionally pinned to a version) against a small set of user-configured registries, closing the vision document's aspirational install-by-identifier command (section 9.2: "patchcord plugin install io.patchcord.postgresql@1.0.0", "depuis un registre futur") and unblocking bundle updates (ADR-0044).	Package registry resolves a package id (optionally pinned to a version) against a small set of user-configured registries, closing the vision document's aspirational install-by-identifier command (section 9.2: "patchcord plugin install io.patchcord.postgresql@1.0.0", "depuis un registre futur") and unblocking bundle updates (ADR-0044).
runs Package runs is the run manager: it persists workflow versions, runs and their steps, and orchestrates execution on top of internal/workflow's engine and an ActionExecutor (typically internal/plugins.Supervisor).	Package runs is the run manager: it persists workflow versions, runs and their steps, and orchestrates execution on top of internal/workflow's engine and an ActionExecutor (typically internal/plugins.Supervisor).
runtime Package runtime manages the Patchcord agent's lifecycle: opening its database, launching and supervising its installed plugins, binding its local HTTP API, and shutting everything down cleanly on cancellation.	Package runtime manages the Patchcord agent's lifecycle: opening its database, launching and supervising its installed plugins, binding its local HTTP API, and shutting everything down cleanly on cancellation.
scheduler Package scheduler fires workflows whose trigger is "schedule" (internal/workflow.Trigger, ADR-0035) on their declared cron cadence, unattended — no HTTP request or CLI invocation supplies inputs or bindings the way a manual run does.	Package scheduler fires workflows whose trigger is "schedule" (internal/workflow.Trigger, ADR-0035) on their declared cron cadence, unattended — no HTTP request or CLI invocation supplies inputs or bindings the way a manual run does.
secrets Package secrets resolves logical references to secret values.	Package secrets resolves logical references to secret values.
signing Package signing manages Ed25519 key pairs used to sign and verify packages (.patchcord-plugin, .patchcord-app, .patchcord-bundle).	Package signing manages Ed25519 key pairs used to sign and verify packages (.patchcord-plugin, .patchcord-app, .patchcord-bundle).
trust Package trust is the trust store for package signing keys (ADR-0043): it answers "is this public key approved to sign this package id?" — nothing about whether a signature is cryptographically valid in the first place, that's internal/packaging.Verify's job.	Package trust is the trust store for package signing keys (ADR-0043): it answers "is this public key approved to sign this package id?" — nothing about whether a signature is cryptographically valid in the first place, that's internal/packaging.Verify's job.
version Package version holds the agent binary's build-time version metadata.	Package version holds the agent binary's build-time version metadata.
workflow Package workflow implements the workflow engine: parsing and validating declarative workflow definitions, resolving their expressions, and the explicit state machines Run and Step transitions follow.	Package workflow implements the workflow engine: parsing and validating declarative workflow definitions, resolving their expressions, and the explicit state machines Run and Step transitions follow.
migrations Package migrations embeds the SQL files internal/persistence applies to bring the agent's SQLite schema up to date.	Package migrations embeds the SQL files internal/persistence applies to bring the agent's SQLite schema up to date.
plugins
examples/encoding command Command encoding is an example plugin bundling three small, unrelated utility actions that don't individually warrant their own supervised process — "base64.encode@1", "base64.decode@1", "hash.sha256@1", and "uuid.generate@1" — the same "several actions, one process" pattern the "text" example plugin already establishes for string operations.	Command encoding is an example plugin bundling three small, unrelated utility actions that don't individually warrant their own supervised process — "base64.encode@1", "base64.decode@1", "hash.sha256@1", and "uuid.generate@1" — the same "several actions, one process" pattern the "text" example plugin already establishes for string operations.
examples/http command Command http is the reference example plugin demonstrating a real connector-consuming action (vision document section 7.4's http.request example): it contributes one connector type, "http.connection@1", and one action, "http.request@1", which requires that connector to be bound.	Command http is the reference example plugin demonstrating a real connector-consuming action (vision document section 7.4's http.request example): it contributes one connector type, "http.connection@1", and one action, "http.request@1", which requires that connector to be bound.
examples/json command Command json is an example plugin contributing basic JSON manipulation actions — "json.parse@1", "json.stringify@1", "json.jsonpath@1", and "json.merge@1" — the kind of utility operations most real workflows need (e.g.	Command json is an example plugin contributing basic JSON manipulation actions — "json.parse@1", "json.stringify@1", "json.jsonpath@1", and "json.merge@1" — the kind of utility operations most real workflows need (e.g.
examples/mysql command Command mysql is the fourth reference example plugin demonstrating a real connector-consuming action, mirroring plugins/examples/postgresql for a second SQL engine: it contributes one connector type, "mysql.connection@1", and two actions — "mysql.query@1" and "mysql.execute@1" — the same query/execute pair the vision document names for PostgreSQL (section 8.3), so a workflow author switching engines only changes which connector/action ids they bind, not the shape of a step.	Command mysql is the fourth reference example plugin demonstrating a real connector-consuming action, mirroring plugins/examples/postgresql for a second SQL engine: it contributes one connector type, "mysql.connection@1", and two actions — "mysql.query@1" and "mysql.execute@1" — the same query/execute pair the vision document names for PostgreSQL (section 8.3), so a workflow author switching engines only changes which connector/action ids they bind, not the shape of a step.
examples/openai command Command openai is the second reference example plugin demonstrating a real connector-consuming action, this time targeting the OpenAI Chat Completions API specifically: it contributes one connector type, "openai.connection@1", and one action, "ai.generate_text@1" (the action id is deliberately generic — see the vision document's own example list, section 7.4 — so a future provider plugin could contribute the same action bound to a different connector, without workflows changing).	Command openai is the second reference example plugin demonstrating a real connector-consuming action, this time targeting the OpenAI Chat Completions API specifically: it contributes one connector type, "openai.connection@1", and one action, "ai.generate_text@1" (the action id is deliberately generic — see the vision document's own example list, section 7.4 — so a future provider plugin could contribute the same action bound to a different connector, without workflows changing).
examples/postgresql command Command postgresql is the third reference example plugin demonstrating a real connector-consuming action (vision document sections 7.3/8.3): it contributes one connector type, "postgresql.connection@1", and two actions — "postgresql.query@1" and "postgresql.execute@1" — the exact pair named as the worked example in the vision document (section 8.3).	Command postgresql is the third reference example plugin demonstrating a real connector-consuming action (vision document sections 7.3/8.3): it contributes one connector type, "postgresql.connection@1", and two actions — "postgresql.query@1" and "postgresql.execute@1" — the exact pair named as the worked example in the vision document (section 8.3).
examples/text command Command text is the reference example plugin from the vision document (section 20): a small library of text actions — "text.uppercase@1", "text.lowercase@1", "text.join@1", "text.split@1", "text.echo_connector@1" — all served by the same process.	Command text is the reference example plugin from the vision document (section 20): a small library of text actions — "text.uppercase@1", "text.lowercase@1", "text.join@1", "text.split@1", "text.echo_connector@1" — all served by the same process.
examples/time command Command time is an example plugin contributing basic date/time actions — "time.now@1", "time.format@1", "time.parse@1", and "time.add@1" — the kind of utility operations most real workflows need (timestamps, expiries, scheduling windows).	Command time is an example plugin contributing basic date/time actions — "time.now@1", "time.format@1", "time.parse@1", and "time.add@1" — the kind of utility operations most real workflows need (timestamps, expiries, scheduling windows).
sdk
go-plugin Package patchcord is the official SDK for writing Patchcord plugins in Go.	Package patchcord is the official SDK for writing Patchcord plugins in Go.