podium

module

v0.1.1 Latest Latest Go to latest Published: May 12, 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

A catalog for reusable AI agent artifacts, with tools that translate those artifacts into harness-specific formats and help you share them with others.

Podium stores skills, agents, commands, rules, hooks, contexts, and MCP server registrations as portable artifacts. A developer can keep a local filesystem catalog and run podium sync to write harness-native files into a workspace. A team can put the same artifacts behind a registry server for runtime discovery, identity-aware visibility, audit, and shared governance. In server mode, teams usually keep the catalog in one or more Git repositories; the registry ingests those tracked refs and builds the effective catalog it serves.

Documentation • Hello world • Contributing

Status: pre-release. The initial v1 implementation lives on the initial-implementation branch. No tagged release has been published; install by building from source. Open an issue or discussion for design feedback or bug reports.

Setups

Podium can run from a filesystem catalog or from a registry server:

Filesystem catalog: file-based artifacts plus the Podium CLI. This mode fits individual use, prototypes, CI, and small shared repositories.
Registry server: artifacts in one or more Git repositories, plus the Podium server, CLI, MCP server, and SDKs. Git stores catalog history and review flow; the registry ingests the configured refs and composes the effective catalog. This mode adds runtime discovery, identity-aware visibility, audit, and server-side composition.

Concepts Compare deployment setups

Highlights

Cross-harness delivery. Pluggable harness adapters translate canonical artifacts into Claude Code, Claude Desktop, Claude Cowork, Cursor, Codex, Gemini CLI, OpenCode, Pi, Hermes, or a custom runtime. The adapter roster with documentation links is in Configure your harness.
Artifact organization based on domains and subdomains. Keep artifacts organized in folders and subfolders, where each folder defines a domain.
Selective materialization. Sync a subset of the catalog into a workspace. Define profiles to quickly switch between scopes.
Layered composition. Compose the catalog from multiple sources with deterministic merge and explicit precedence. (Requires the Podium registry server.)
Per-layer visibility. Declare who can see what: each layer can be public, organization-wide, scoped to OIDC groups, or restricted to specific users. (Requires the Podium registry server.)
Agent-driven progressive discovery. Discovery tools for traversing domains and searching artifacts. (Requires the Podium MCP server or SDK.)
Lazy artifact loading. Materialize artifact files into the workspace as they are loaded. (Requires the Podium MCP server or SDK.)

Every capability is covered by the integration test suite.

'Hello world' example

The commands below describe the target v1 CLI flow.

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. -->

Point Podium at the directory and set the harness:

cd workspace
podium init --registry ~/podium-artifacts/ --harness claude-code
podium sync

Open Claude Code in the project. Claude Code can discover the materialized skill in its native location.

Full quickstart

How it works

Podium consists of:

A registry: the catalog of artifacts. Backed either by a folder on disk (filesystem mode) or by a Podium server (standalone or standard mode). Built-in source types are git (a remote Git repo at a tracked ref) and local (a filesystem path); the LayerSourceProvider SPI lets deployments add custom sources (S3 buckets, OCI registries, HTTP archives).
Consumers: built-in consumers are podium sync, the MCP server, and the language SDKs. Custom consumers can build against the HTTP API directly.

In server mode, the server holds the catalog; consumers reach it over HTTP and identity-aware composition runs server-side:

   Git repos / local paths ──────────┐
   (one or more layer sources)       │
                                     ▼
                       ┌─────────────────────────┐
                       │ Podium server           │
                       │  HTTP/JSON API          │
                       │  Postgres + pgvector    │
                       │  layer composition      │
                       │  visibility filtering   │
                       │  dependency graph       │
                       └────────────▲────────────┘
                                    │
                  OAuth-attested identity (every call)
                                    │
       ┌────────────────────────────┼────────────────────────────┐
       │                            │                            │
┌──────┴───────┐          ┌─────────┴──────┐          ┌──────────┴─────┐
│ Language SDKs│          │ MCP server     │          │ podium sync    │
│ (py, ts)     │          │ (in-process)   │          │ (CLI)          │
└──────────────┘          └────────────────┘          └────────────────┘
LangChain, Bedrock,       Claude Code, Cursor,        File-based
custom orchestrators      Cowork, OpenCode, Pi,       harnesses
                          Hermes

In filesystem mode, the catalog is a folder. podium sync reads it directly, with no server, HTTP, or auth, and writes harness-native files to a project. The MCP server and language SDKs require a server.

Component	Role
Podium server	HTTP API; layer composition; visibility filtering; manifest indexing; hybrid retrieval; signing; audit.
MCP server	In-process bridge for MCP-speaking hosts. Exposes the discovery and load meta-tools. Requires a server.
`podium sync`	CLI (and library) that materializes the user's effective view to disk via the harness adapter. Either mode.
Language SDKs	Thin HTTP clients for programmatic runtimes (LangChain, Bedrock, custom orchestrators). Requires a server.

Layer composition, visibility filtering, and harness adaptation run through the same shared Go library regardless of mode: embedded behind the server's HTTP API in server mode; invoked directly by podium sync in filesystem mode. Migrating between modes is mechanical and produces equivalent output for the same artifact directory.

Documentation

Documentation site: organized by role (author / consume / deploy). Start with Getting Started for the quickstart, concepts, and architecture.
Contributing, Governance, Security.

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 Tier 2 tests against real Postgres, S3,
                        # Sigstore, and embedding providers
                        # (configured via PODIUM_LIVE_* env vars).
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 about 10 seconds 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 helps validate the adapter SPI shape.
Sketch a LayerSourceProvider plugin: a custom source backend (S3, OCI, internal CMS) helps validate 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 Command podium is the unified Podium CLI.	Command podium is the unified Podium CLI.
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.
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.
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.
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/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).
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 filesystem-source materialization (spec §7.5, §13.11): open the filesystem registry, walk every visible artifact in the caller's effective view, run the configured HarnessAdapter, and write atomically through pkg/materialize.	Package sync orchestrates filesystem-source materialization (spec §7.5, §13.11): open the filesystem registry, walk every visible artifact in the caller's effective view, run the configured HarnessAdapter, and write atomically through pkg/materialize.
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.
tools
coverage command Command coverage wraps `go test -coverprofile` and enforces budgets.	Command coverage wraps `go test -coverprofile` and enforces budgets.
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.
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 static SPA assets (§13.10 web UI) to callers that mount them at /ui/.	Package web exposes the static SPA assets (§13.10 web UI) to callers that mount them at /ui/.