podium

module

v0.4.0 Latest Latest Go to latest Published: Sep 5, 2026 License: MIT

Details

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

Repository

github.com/lennylabs/podium

Links

Open Source Insights

README ¶

Podium

One catalog. Every harness.

A catalog for reusable AI skills and other agent artifacts, with tools that translate them into harness-specific formats.

Podium holds skills, agents, commands, rules, hooks, contexts, and MCP server registrations as canonical artifacts. An author writes an artifact once, and a harness adapter translates it into the layout the target runtime expects. The same finance/rollback directory becomes .claude/skills/rollback/SKILL.md for Claude Code and .cursor/skills/rollback/SKILL.md for Cursor, with no per-harness copy in the catalog.

An artifact is a directory, and the directory carries its dependencies. A skill that ships scripts/verify_revision.py beside its SKILL.md delivers that script into every layout it reaches, workspace trees and published marketplace repositories alike. Selecting the artifact selects its files.

Documentation • Install • Features • Hello world • Contributing

Status: 0.3.x, early release. The CLI, server, MCP bridge, and SDKs are all published, but the surface and behavior may still shift before 1.0. Open an issue or discussion for bug reports, missing use cases, or design feedback.

Install

The Podium CLI ships the podium, podium-server, and podium-mcp binaries on every supported platform. Pick whichever channel matches your setup.

macOS / Linux (Homebrew):

brew tap lennylabs/tap
brew install podium

Windows (Scoop):

scoop bucket add lennylabs https://github.com/lennylabs/scoop-bucket
scoop install podium

Direct binary download: grab podium-<os>-<arch> (or the .tar.gz / .zip bundle that includes every binary) from the latest release.

Container (for the registry server): docker pull ghcr.io/lennylabs/podium-server:latest.

SDKs for programmatic consumers:

pip install podium-sdk             # Python; imports as `from podium import ...`
npm install @lennylabs/podium-sdk  # TypeScript

From source (Go 1.26+ required):

git clone https://github.com/lennylabs/podium.git
cd podium && go build -o ~/.local/bin/podium ./cmd/podium

Features

Cross-harness delivery. A harness adapter maps a canonical artifact onto Claude Code, Claude Desktop, Claude Cowork, Cursor, Codex, Gemini CLI, OpenCode, Pi, Hermes, or a custom runtime, and decides the on-disk destination for each artifact type. podium sync writes a workspace tree the harness reads directly. An entry of kind: marketplace under targets: renders the same catalog into the git-repo distribution a harness imports (a plugin marketplace, extension, package, or tap) and runs an operator-configured workflow to push it. Bundled files ride along into both wherever the destination layout has a place for them. In the workspace tree a harness-native rule is a single file and an mcp-server registration is a config-file merge, so bundled files on those two types are not written. See Configure your harness and Marketplace publishing.
Domains and subdomains. The directory layout defines the domain hierarchy. finance is a domain, finance/ap is a subdomain, and finance/ap/pay-invoice is the canonical ID of an artifact under it. A domain folder can carry a DOMAIN.md that adds a description, keywords, and featured artifacts. See Domains.
Selective materialization. A workspace rarely needs the whole catalog. podium sync materializes the subset named by include globs, exclude globs, and artifact types, and a named profile stores that subset in sync.yaml so one command switches between scopes. See Selective materialization.
Progressive discovery. An agent that speaks MCP traverses domains with load_domain, finds candidates with search_domains and search_artifacts, and calls load_artifact on the one it picks. Only that last call materializes anything, and it writes the artifact's bundled files at the same time, so a catalog larger than any system prompt stays usable. Requires a Podium server, reached through the MCP server or an SDK. See Browsing the catalog.
Layered composition. One catalog assembles from several independent sources in a declared order, with deterministic merge, explicit precedence, and extends: for an artifact that inherits and refines a lower one. A catalog on disk composes its subdirectories as ordered layers through .registry-config. A server adds registered layers, remote Git sources, and visibility. See Layered composition.
Access control. Each layer declares who can see it: everyone, every authenticated user in the organization, the members of named OIDC groups, or named users. The registry evaluates visibility on every call and composes the caller's effective view from the layers that pass. Requires a Podium server with an identity provider configured. See Access control.

Why Podium covers each feature in more detail, when Podium applies, when a simpler alternative is enough, and how it compares to adjacent products.

Deployment tiers

Podium runs in tiers. Each tier keeps everything the tier below it does and adds server-side capability.

Tier	Server-side deployment	Catalog source	Materialization	What the tier adds
Local	None	A folder, read from disk	User-driven sync	Authoring, lint, sync, domains, profiles, and ordered layers from disk
Single node	One binary	One or more folders or remote Git repos	User-driven sync, or agent-driven on demand	Everything in local, plus discovery through MCP or the SDKs, hybrid search, registered and remote layers with visibility, and one audit log
Clustered	Replicas, Postgres, and object storage	One or more folders or remote Git repos	User-driven sync, or agent-driven on demand	Everything in single node, plus multi-tenancy, SCIM group sync, signing with a transparency log, and high availability

The artifacts are the same in every tier. The catalog on disk does not change when the deployment changes, and the same shared Go library parses, composes, and materializes it everywhere, so a given target and profile produce bit-identical output. Deployment covers picking a tier and moving between them.

Server-side integrations

A registry process reaches out to several backing services. Each one has a default that a single-node deployment runs without extra infrastructure, and each one is selectable per deployment.

Integration	Out of the box	Compatible alternatives
Metadata store	SQLite	Postgres
Object storage	Local filesystem	S3 or any S3-compatible service
Vector index	`sqlite-vec`	`pgvector`, Pinecone, Weaviate Cloud, and Qdrant Cloud
Embeddings	`ollama`, falling back to BM25 when unreachable	OpenAI, Voyage, Cohere, and Ollama, or a self-embedding vector backend
Identity	None	`oidc-jwt`, `trusted-headers`, and `injected-session-token`
Layer sources	Git and local paths	Custom sources through the `LayerSourceProvider` SPI

Nothing in the right column is required to start. pgvector becomes the vector default once the metadata store is Postgres. A single node defaults the provider to ollama and a Postgres-backed deployment to openai, but neither ships in the binary. Hybrid search needs that provider reachable from the registry, or a managed vector backend that embeds on ingest; with neither, search_artifacts runs BM25 keyword search over manifest text. oidc-jwt verifies tokens an external IdP issued, so it needs that IdP's issuer URL and an audience the IdP mints tokens for. trusted-headers reads the identity headers a fronting gateway injects and contacts no IdP. injected-session-token verifies tokens signed by a runtime key in the trusted key set the registry reads at startup from PODIUM_RUNTIME_KEYS_PATH, written with podium admin runtime register --keys-file, against the audience configured for the registry. SCIM provisions groups alongside a provider rather than replacing one. At cluster scale, Postgres and object storage become requirements, because registry replicas need shared state. See Server-side integrations.

'Hello world' example

After installing the podium CLI, create a skill directory with a SKILL.md file for agent-facing instructions and an ARTIFACT.md file for Podium metadata:

~/podium-artifacts/personal/hello/greet/SKILL.md

---
name: greet
description: Greet the user by name and tell them today's date.
---

Greet the user by their first name. Tell them today's date.

~/podium-artifacts/personal/hello/greet/ARTIFACT.md

---
type: skill
version: 1.0.0
tags: [demo, hello-world]
---

<!-- Skill body lives in SKILL.md. -->

Anything else in the directory is a bundled resource that travels with the artifact, so give the skill a script to call:

~/podium-artifacts/personal/hello/greet/scripts/today.py

from datetime import date

print(date.today().strftime("%A, %-d %B %Y"))

Point Podium at the directory and set the harness:

cd ~/projects/your-project
podium init --registry ~/podium-artifacts/ --harness claude-code
podium sync

adapter: claude-code
target:  /Users/alice/projects/your-project
artifacts:
  - personal/hello/greet  [podium-artifacts]
      .claude/skills/greet/SKILL.md
      .claude/skills/greet/scripts/today.py

Open Claude Code in the project and it discovers the skill in its native location. Point the same catalog at another harness and the adapter decides where everything lands:

podium sync --harness cursor

adapter: cursor
target:  /Users/alice/projects/your-project
artifacts:
  - personal/hello/greet  [podium-artifacts]
      .cursor/skills/greet/SKILL.md
      .cursor/skills/greet/scripts/today.py

Nothing in the catalog changed between those two runs. Each run reconciles the whole target against the lock file, so the second one removed the .claude/ files the first wrote. The layer bracket names the filesystem layer the artifact came from, which is the basename of the registry directory.

Full quickstart

Documentation

Documentation site: the docs home is Overview, and the sections are organized by task (author, consume, deploy, and reference).
Start here: Why Podium for the feature-by-feature claim and the comparisons, Quickstart for the first artifact, Concepts for the vocabulary, and How it works for the architecture.
Project: Contributing, Governance, Security, and Implementation status.

Build and test

Building from source requires:

Go 1.26 or later for the registry, CLI, and MCP server.
Python 3.10 or later for the podium-py SDK.
Node.js 20 or later for the @lennylabs/podium-sdk TypeScript SDK.

Clone the repository, then:

go build ./...           # Build every Go binary in the module.
make test                # Run the full Go test suite.
make test-live           # Run the suite against the local Postgres and
                         # MinIO services started by `make services-up`.
make test-live-external  # Run the suite against the managed vector and
                         # embedding services (PODIUM_LIVE_EXTERNAL=1).
make coverage            # Run with -coverprofile and print a summary.
make help                # List every make target.

The SDK suites run independently:

cd sdks/podium-py
pip install -e .
pytest

cd sdks/podium-ts
npm install
npm test

The complete Go suite runs in one to two minutes on a recent laptop. The full development setup is in docs/about/contributing.md.

Contributing

Today's most useful contributions:

Open issues or discussions: questions, missing use cases, bug reports.
Run the test suite from source and report failures or environment-specific issues.
Sketch a harness adapter: prototyping an adapter for a new harness validates the HarnessAdapter SPI against a runtime nobody has targeted yet.
Sketch a LayerSourceProvider plugin: a custom source backend (S3, OCI, internal CMS) validates that SPI surface.
Fix typos and broken links: small documentation PRs are welcome any time.

See CONTRIBUTING.md and GOVERNANCE.md.

License

MIT

Directories ¶

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

Path	Synopsis
cmd
podium command `podium artifact scaffold` writes a new artifact directory at the given path.	`podium artifact scaffold` writes a new artifact directory at the given path.
podium-mcp command Command podium-mcp is the MCP server bridge described in spec §6.	Command podium-mcp is the MCP server bridge described in spec §6.
podium-server command Command podium-server runs the Podium registry as a long-lived HTTP server.	Command podium-server runs the Podium registry as a long-lived HTTP server.
internal
buildinfo Package buildinfo carries the version, commit, and build date that each Podium binary reports.	Package buildinfo carries the version, commit, and build date that each Podium binary reports.
clock Package clock is the only time source production code is allowed to consume.	Package clock is the only time source production code is allowed to consume.
serverboot Package serverboot is the shared bootstrap for the registry HTTP server.	Package serverboot is the shared bootstrap for the registry HTTP server.
testenv Package testenv loads an optional env file so a single file can supply the credentials the integration and live tests read.	Package testenv loads an optional env file so a single file can supply the credentials the integration and live tests read.
testharness
testharness/cmdharness Package cmdharness builds and runs the Podium binaries during tests so integration and end-to-end tests exercise the real CLI rather than the internal library APIs.	Package cmdharness builds and runs the Podium binaries during tests so integration and end-to-end tests exercise the real CLI rather than the internal library APIs.
testharness/registryharness Package registryharness wraps a filesystem-source registry behind a httptest.Server so integration tests exercise the real HTTP API without paying for a TCP socket.	Package registryharness wraps a filesystem-source registry behind a httptest.Server so integration tests exercise the real HTTP API without paying for a TCP socket.
testpg Package testpg gives a test binary its own Postgres database.	Package testpg gives a test binary its own Postgres database.
pkg
adapter Package adapter defines the HarnessAdapter SPI (spec §6.7) and ships the none adapter, which writes the canonical artifact layout as-is.	Package adapter defines the HarnessAdapter SPI (spec §6.7) and ships the none adapter, which writes the canonical artifact layout as-is.
audit Package audit implements the registry audit log per spec §8 and the hash-chained integrity check from §8.6.	Package audit implements the registry audit log per spec §8 and the hash-chained integrity check from §8.6.
dependency Package dependency implements the cross-type dependency graph and reverse index from spec §4.7.3 plus the impact-analysis surface from §4.7.5.	Package dependency implements the cross-type dependency graph and reverse index from spec §4.7.3 plus the impact-analysis surface from §4.7.5.
domain Package domain implements DOMAIN.md merging, glob resolution, and the discovery-rendering rules from spec §4.5.	Package domain implements DOMAIN.md merging, glob resolution, and the discovery-rendering rules from spec §4.5.
embedding Package embedding implements the §4.7 EmbeddingProvider SPI plus the four built-in providers (`openai`, `voyage`, `cohere`, `ollama`).	Package embedding implements the §4.7 EmbeddingProvider SPI plus the four built-in providers (`openai`, `voyage`, `cohere`, `ollama`).
hook Package hook defines the MaterializationHook SPI from spec §9.1 / §6.6.	Package hook defines the MaterializationHook SPI from spec §9.1 / §6.6.
identity Package identity exposes the IdentityProvider SPI per spec §6.3, plus the two built-in providers oauth-device-code and injected-session-token.	Package identity exposes the IdentityProvider SPI per spec §6.3, plus the two built-in providers oauth-device-code and injected-session-token.
layer Package layer implements the LayerComposer (spec §4.6) plus the visibility evaluator that runs before composition.	Package layer implements the LayerComposer (spec §4.6) plus the visibility evaluator that runs before composition.
layer/source Package source defines the LayerSourceProvider SPI (spec §9.1, §4.6 "Source types"), plus the built-in local and git providers.	Package source defines the LayerSourceProvider SPI (spec §9.1, §4.6 "Source types"), plus the built-in local and git providers.
layer/webhook Package webhook implements the webhook signature verification half of §7.3.1 ingest.	Package webhook implements the webhook signature verification half of §7.3.1 ingest.
lint Package lint runs ingest-time validation across artifact and domain manifests.	Package lint runs ingest-time validation across artifact and domain manifests.
manifest Package manifest defines the canonical artifact and domain manifest types per spec §4.3 (Artifact Manifest Schema), §4.3.4 (SKILL.md compliance), and §4.5.1 (DOMAIN.md).	Package manifest defines the canonical artifact and domain manifest types per spec §4.3 (Artifact Manifest Schema), §4.3.4 (SKILL.md compliance), and §4.5.1 (DOMAIN.md).
materialize Package materialize writes adapter output to disk under the sandbox contract from spec §6.6 and §6.7: atomic per-file write, no writes outside the destination root, no network, no subprocesses.	Package materialize writes adapter output to disk under the sandbox contract from spec §6.6 and §6.7: atomic per-file write, no writes outside the destination root, no network, no subprocesses.
metrics Package metrics implements the §13.8 Prometheus instrumentation surface for the registry and the MCP server.	Package metrics implements the §13.8 Prometheus instrumentation surface for the registry and the MCP server.
notification Package notification implements the §9 NotificationProvider SPI.	Package notification implements the §9 NotificationProvider SPI.
objectstore Package objectstore implements the §4.1 inline-cutoff path for large bundled resources.	Package objectstore implements the §4.1 inline-cutoff path for large bundled resources.
overlay Package overlay implements the LocalOverlayProvider SPI from spec §6.4.	Package overlay implements the LocalOverlayProvider SPI from spec §6.4.
registry/core Package core implements the meta-tool operations against a Store (spec §2.2 shared library code, §5 meta-tools).	Package core implements the meta-tool operations against a Store (spec §2.2 shared library code, §5 meta-tools).
registry/filesystem Package filesystem implements the filesystem-source registry described in spec §13.11.	Package filesystem implements the filesystem-source registry described in spec §13.11.
registry/ingest Package ingest implements the ingest pipeline described in spec §7.3.1: fetch a layer's snapshot, walk the diff, run lint as defense in depth, validate immutability, content-hash, store manifest and bundled resources, and emit an event.	Package ingest implements the ingest pipeline described in spec §7.3.1: fetch a layer's snapshot, walk the diff, run lint as defense in depth, validate immutability, content-hash, store manifest and bundled resources, and emit an event.
registry/projection Package projection builds the canonical §4.7 text projections that the registry embeds.	Package projection builds the canonical §4.7 text projections that the registry embeds.
registry/server Package server exposes the registry HTTP/JSON API (spec §5, §6.10).	Package server exposes the registry HTTP/JSON API (spec §5, §6.10).
scim Package scim implements the §6.3.1 SCIM 2.0 receiver.	Package scim implements the §6.3.1 SCIM 2.0 receiver.
sign Package sign exposes the SignatureProvider SPI (spec §9.1) plus the medium-and-above verification policy enforced at materialization time (§4.7.9).	Package sign exposes the SignatureProvider SPI (spec §9.1) plus the medium-and-above verification policy enforced at materialization time (§4.7.9).
spi Package spi defines the structured error envelope that Podium's built-in pluggable interfaces (SPIs, §9.1) return.	Package spi defines the structured error envelope that Podium's built-in pluggable interfaces (SPIs, §9.1) return.
store Package store defines RegistryStore SPI (spec §9.1) plus the shared types every backend implementation works with: tenant identity, manifest metadata records, dependency edges, layer config rows, and admin grants.	Package store defines RegistryStore SPI (spec §9.1) plus the shared types every backend implementation works with: tenant identity, manifest metadata records, dependency edges, layer config rows, and admin grants.
store/storetest Package storetest is the conformance suite for RegistryStore implementations (spec §9.1, §9.3).	Package storetest is the conformance suite for RegistryStore implementations (spec §9.1, §9.3).
sync Package sync orchestrates materialization (spec §7.5, §13.11) for both registry sources: a filesystem registry (walk the local layers) and a server registry (read the effective view over the §7.5 HTTP API).	Package sync orchestrates materialization (spec §7.5, §13.11) for both registry sources: a filesystem registry (walk the local layers) and a server registry (read the effective view over the §7.5 HTTP API).
tracing Package tracing wires the §13.8 OpenTelemetry trace export and W3C Trace Context propagation for the registry and the MCP bridge.	Package tracing wires the §13.8 OpenTelemetry trace export and W3C Trace Context propagation for the registry and the MCP bridge.
typeprovider Package typeprovider implements the §9 TypeProvider SPI.	Package typeprovider implements the §9 TypeProvider SPI.
vector Package vector implements the §4.7 RegistrySearchProvider SPI.	Package vector implements the §4.7 RegistrySearchProvider SPI.
vector/vectortest Package vectortest is the conformance suite every vector.Provider implementation must pass.	Package vectortest is the conformance suite every vector.Provider implementation must pass.
version Package version implements semver pinning and content-hash derivation for spec §4.7.6 (Version Resolution and Consistency) and §4.7 (immutability invariant).	Package version implements semver pinning and content-hash derivation for spec §4.7.6 (Version Resolution and Consistency) and §4.7 (immutability invariant).
webhook Package webhook implements §7.3.2 outbound webhook delivery.	Package webhook implements §7.3.2 outbound webhook delivery.
test
harness_integration Package harness_integration drives the real agent-harness binaries (Claude Code, Codex, Gemini, OpenCode, …) against a project materialized by the real `podium sync`, to confirm a harness actually accepts and discovers Podium's output.	Package harness_integration drives the real agent-harness binaries (Claude Code, Codex, Gemini, OpenCode, …) against a project materialized by the real `podium sync`, to confirm a harness actually accepts and discovers Podium's output.
tools
coverage command Command coverage wraps `go test -coverprofile` and enforces budgets.	Command coverage wraps `go test -coverprofile` and enforces budgets.
doccov command Command doccov reports runnable-command coverage across Podium's documentation.	Command doccov reports runnable-command coverage across Podium's documentation.
internal/specparser Package specparser scans a Podium checkout for spec citations and produces the data the speccov and phasegate tools format.	Package specparser scans a Podium checkout for spec citations and produces the data the speccov and phasegate tools format.
matrix command Command matrix audits coverage of documented spec matrices: every cell of every matrix should have at least one test that claims it via a `// Matrix: §X.Y (key1, key2, ...)` annotation.	Command matrix audits coverage of documented spec matrices: every cell of every matrix should have at least one test that claims it via a `// Matrix: §X.Y (key1, key2, ...)` annotation.
minttoken command Command minttoken generates a runtime RSA signing key and mints RS256 injected-session-token JWTs for the manual validation scenarios in test/manual-validation.md.	Command minttoken generates a runtime RSA signing key and mints RS256 injected-session-token JWTs for the manual validation scenarios in test/manual-validation.md.
speccov command Command speccov reports spec-citation coverage across Podium's test suite.	Command speccov reports spec-citation coverage across Podium's test suite.
web Package web exposes the built §13.10 web-UI bundle to callers that mount it at /app/.	Package web exposes the built §13.10 web-UI bundle to callers that mount it at /app/.