cisternal

Status: alpha. APIs may change without notice before 1.0.

Cisternal is a shared telemetry substrate and agent-asset export toolkit for the Praxia tool family. It has two parts:

• Telemetry — a lightweight, non-blocking event pipeline (JSONL export, OTLP export, MCP-tool registration wrapper) for instrumenting Python tools and MCP servers.
• Agent-asset export — a CLI that takes a registry of MCP tools/commands and emits native plugin/config bundles for downstream coding-agent surfaces: Claude Code, Cursor, GitHub Copilot, Antigravity, OpenCode, Pi, and JCode.

Install

pip install cisternal

For OTLP export support:

pip install "cisternal[otlp]"

Telemetry quickstart

import cisternal

cisternal.init()  # log_dir defaults to ~/.cisternal/logs, or env-resolved

with cisternal.span("my.operation", request_id="abc123"):
    do_work()

cisternal.emit_event("my.custom_event", tool="foo")
print(cisternal.status())

Check your effective telemetry configuration from the shell:

cisternal telemetry doctor
cisternal telemetry doctor --json --strict

Registering MCP tools

import cisternal

@cisternal.tool
def my_tool(x: int) -> int:
    return x * 2

registry = cisternal.wire(server, app, adapter=my_adapter)

cisternal.tool is a pure-metadata decorator — it returns the original function unchanged. cisternal.wire() snapshots the registry at call time and registers each tool on a FastMCP server (and optionally a Cyclopts CLI app), returning a WiredRegistry for introspection.

Agent-asset export

# Preview what would be written, without touching disk
cisternal assets export --dry-run

# Write bundles for specific surfaces
cisternal assets export --out ./dist/agent-assets

# Inspect or validate an existing bundle
cisternal assets inspect
cisternal assets validate

Install as a real Claude Code plugin

cisternal assets export only writes files — nothing picks them up until something registers them. cisternal assets install does both steps: it writes the bundle, then drives the real claude CLI to register it as a local marketplace and install it, so its skills/agents/MCP config actually load in a Claude Code session.

Requires a [plugin.marketplace] table in your manifest:

[plugin]
name = "my-plugin"
version = "1.0.0"

[plugin.marketplace]
name = "my-plugin-marketplace"

[plugin.marketplace.owner]
name = "Your Name"

cisternal assets install --manifest .praxia/manifest.toml
# writes the bundle to ./, then runs:
#   claude plugin marketplace add .
#   claude plugin install my-plugin@my-plugin-marketplace --scope project

Both underlying claude commands are idempotent — re-running install is safe. --scope project (the default) registers the plugin in this project's .claude/settings.json, so anyone who clones the repo needs only one manual claude plugin install my-plugin@my-plugin-marketplace (Claude Code's own trust-on-first-use step — not something this command tries to bypass). To remove it later: claude plugin uninstall my-plugin@my-plugin-marketplace and claude plugin marketplace remove my-plugin-marketplace.

Supported export targets: Claude Code, Cursor, GitHub Copilot, Antigravity, OpenCode, Pi, JCode.

The CLI is fastmcp-free by design — cisternal.cli imports and runs even in environments without fastmcp installed; asset-export logic never depends on the telemetry/registration surface.

Design notes

• Telemetry emission never raises: if the pipeline isn't initialized, emit_event/span are no-ops.
• Registry state is process-scoped — call cisternal.clear_registry() between tests to avoid cross-test contamination.
• The M2 wire-time MCP callable is a pure passthrough: telemetry and shape adaptation are exclusively owned by the telemetry middleware, never by the registration wrapper itself.

License

MIT — see LICENSE.