cairn

module

v0.1.0 Latest Latest Go to latest Published: Sep 12, 2026 License: MIT

Details

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

Repository

github.com/stump-wtf/cairn

Links

Open Source Insights

README ¶

Cairn

AI-native artifact sharing. A pastebin / gist / requestbin for the agent era: pipe anything in, get a shareable, agent-native link back — pbcopy for cairn. Humans post from the CLI and web; agents read, create, comment, and react over MCP. Every artifact is a short URL with provenance, reactions, comments, and a TTL.

cat checkout-web-audit.md | cairn      →  cairn.stump.wtf/9qz1a

Markdown · Code · Image · File · Bundle (multi-file) · Webhook (live requestbin) · Trace (a whole agent run — an OTel-style span waterfall + activity stream).

Surfaces

Web — one app shell for every share type: logo · type · one URL control · share · collapsible metadata + comments panel. Plus the Bin, your artifact listing.
CLI (cairn) — pipe or add files, cairn ls TUI to browse the Bin.
MCP — agents read/create/comment/react over MCP, authorized via MCP OAuth.

The cairn CLI is a single static Go binary — a pure REST client of the core /v1 API, with no domain logic of its own (see ADR-0003). Cross-platform release binaries aren't published yet (tracked for a future goreleaser job); until then, install straight from the module:

go install github.com/stump-wtf/cairn/cmd/cairn@latest

This puts a cairn binary in $(go env GOPATH)/bin (make sure that's on your PATH). Building from a checkout instead:

git clone https://github.com/stump-wtf/cairn && cd cairn
go build -o cairn ./cmd/cairn

Authenticate with a bearer token — mint one from your Cairn server's web Settings page, or use one your deployment operator issued:

cairn login --token <token>       # or: echo "$TOKEN" | cairn login
✓ authorized as sam@stump.rocks · via API

Tokens are stored securely (the OS keychain when available, otherwise a 0600 file under your config directory) — never logged, never printed. Then push:

cat notes.md | cairn              # pipe content in, get a link back
cairn report.pdf                  # or pass a file path
cairn add a.png b.log dump.sql    # push several files as one bundle

cairn --ttl 24h --title "incident notes" incident.md   # optional flags

By default cairn copies the resulting link to your clipboard (best-effort, --no-copy to disable) and shows the server-assigned expiry and access policy — the CLI displays these, it never decides them. Piped/non-interactive output prints only the bare cairn.stump.wtf/<id> link, so it composes cleanly in scripts:

url=$(cat report.md | cairn)

See SPEC-0008 for the full command surface, exit-code taxonomy, and --json mode.

Project docs

docs/DESIGN.md — the product design brief (source of truth).
docs/adrs/ — Architecture Decision Records (MADR).
docs/openspec/specs/ — OpenSpec specifications.

Built spec-first with the sdd workflow: decisions → specs → tracked issues.

Status

Early design. The ADRs and specs in docs/ define the intended architecture; the GitHub issues track the build.

Directories ¶

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

Path	Synopsis
cmd
cairn command Command cairn is the human's terminal surface for Cairn (SPEC-0008): a separate static Go binary that speaks only the documented core /v1 REST/JSON contract (ADR-0003 "Triple Surface Parity" — the CLI is a pure network client, not an in-process adapter, and carries no domain logic).	Command cairn is the human's terminal surface for Cairn (SPEC-0008): a separate static Go binary that speaks only the documented core /v1 REST/JSON contract (ADR-0003 "Triple Surface Parity" — the CLI is a pure network client, not an in-process adapter, and carries no domain logic).
cairnd command Command cairnd is the single static Cairn binary: it serves the web app, the /v1 REST/JSON API, the SSE streams, and the MCP server over one core package (ADR-0012).	Command cairnd is the single static Cairn binary: it serves the web app, the /v1 REST/JSON API, the SSE streams, and the MCP server over one core package (ADR-0012).
gen-chroma-css command Command gen-chroma-css regenerates the code viewer's bundled syntax-theme stylesheet (internal/httpapi/web/assets/chroma.css) from chroma's built-in "github-dark" style, using the exact same formatter options internal/code/render.go highlights with (WithClasses, ClassPrefix "chroma-", PreventSurroundingPre) so the class names the viewer emits and the class names this stylesheet defines can never drift apart.	Command gen-chroma-css regenerates the code viewer's bundled syntax-theme stylesheet (internal/httpapi/web/assets/chroma.css) from chroma's built-in "github-dark" style, using the exact same formatter options internal/code/render.go highlights with (WithClasses, ClassPrefix "chroma-", PreventSurroundingPre) so the class names the viewer emits and the class names this stylesheet defines can never drift apart.
internal
annotation Package annotation owns the polymorphic annotation anchor model shared by reactions and comments: one embedded anchor of {artifact_id, anchor_type, anchor_ref} plus the canonical anchor_key the service derives from it.	Package annotation owns the polymorphic annotation anchor model shared by reactions and comments: one embedded anchor of {artifact_id, anchor_type, anchor_ref} plus the canonical anchor_key the service derives from it.
artifact Package artifact defines the Cairn Artifact aggregate — the single shared unit and aggregate root — and its creation invariants.	Package artifact defines the Cairn Artifact aggregate — the single shared unit and aggregate root — and its creation invariants.
cliclient Package cliclient is the cairn CLI's typed HTTP client over the core /v1 REST API.	Package cliclient is the cairn CLI's typed HTTP client over the core /v1 REST API.
clicmd Package clicmd builds the `cairn` command tree (SPEC-0008 "Command Surface and REST-Client Boundary"): the bare pipe/path ingest command, `add`, `login`, `logout`, and `whoami`.	Package clicmd builds the `cairn` command tree (SPEC-0008 "Command Surface and REST-Client Boundary"): the bare pipe/path ingest command, `add`, `login`, `logout`, and `whoami`.
cliconfig Package cliconfig resolves the cairn CLI's runtime configuration — the API base URL and bearer token — from flags, environment variables, and an on-disk config file, in that precedence order (SPEC-0008 "Configuration and Server Endpoint Resolution").	Package cliconfig resolves the cairn CLI's runtime configuration — the API base URL and bearer token — from flags, environment variables, and an on-disk config file, in that precedence order (SPEC-0008 "Configuration and Server Endpoint Resolution").
cliexit Package cliexit implements the cairn CLI's stable exit-code taxonomy (SPEC-0008 "Machine-Readable Error Mapping and Exit Codes").	Package cliexit implements the cairn CLI's stable exit-code taxonomy (SPEC-0008 "Machine-Readable Error Mapping and Exit Codes").
code Package code renders a code artifact body into the server-side, line numbered, syntax-highlighted HTML fragment the app shell drops into its body slot, together with a navigable symbol outline and the facts the metadata panel shows — the code-viewer analogue of internal/markdown (SPEC-0003 REQ "Code Viewer").	Package code renders a code artifact body into the server-side, line numbered, syntax-highlighted HTML fragment the app shell drops into its body slot, together with a navigable symbol outline and the facts the metadata panel shows — the code-viewer analogue of internal/markdown (SPEC-0003 REQ "Code Viewer").
config Package config loads Cairn's runtime configuration from the environment.	Package config loads Cairn's runtime configuration from the environment.
db Package db owns the Postgres connection lifecycle and schema migrations.	Package db owns the Postgres connection lifecycle and schema migrations.
errs Package errs defines Cairn's domain error taxonomy.	Package errs defines Cairn's domain error taxonomy.
httpapi Package httpapi is the /v1 REST/JSON adapter over the core store service.	Package httpapi is the /v1 REST/JSON adapter over the core store service.
id Package id mints Cairn's short, opaque, public artifact identifiers.	Package id mints Cairn's short, opaque, public artifact identifiers.
imageview Package imageview renders the image share type's server-side body-slot fragment (SPEC-0003 REQ "Image Viewer", issue #69): the image itself plus the static scaffolding image.js progressively enhances into the bespoke pin overlay and the whole-artifact react-below affordance.	Package imageview renders the image share type's server-side body-slot fragment (SPEC-0003 REQ "Image Viewer", issue #69): the image itself plus the static scaffolding image.js progressively enhances into the bespoke pin overlay and the whole-artifact react-below affordance.
markdown Package markdown renders a markdown artifact body into the sanitized, server-side HTML fragment the app shell drops into its body slot, together with the derived table of contents, the deterministic per-block ids anchors resolve against, and a small stats summary the metadata panel shows.	Package markdown renders a markdown artifact body into the sanitized, server-side HTML fragment the app shell drops into its body slot, together with the derived table of contents, the deterministic per-block ids anchors resolve against, and a small stats summary the metadata panel shows.
mcpsession Package mcpsession is the core for tracking MCP agent sessions/connections (issue #76, SPEC-0007, ADR-0004): Joe runs multiple agents over MCP and wants to make sense of which agent is doing what.	Package mcpsession is the core for tracking MCP agent sessions/connections (issue #76, SPEC-0007, ADR-0004): Joe runs multiple agents over MCP and wants to make sense of which agent is doing what.
oauth Package oauth is Cairn's in-process OAuth 2.1 authorization server core (SPEC-0007, ADR-0004).	Package oauth is Cairn's in-process OAuth 2.1 authorization server core (SPEC-0007, ADR-0004).
objectstore MinIO-backed ObjectStore.	MinIO-backed ObjectStore.
outboundhook Package outboundhook delivers post-commit artifact-creation events to configured HTTP targets (outbound webhooks).	Package outboundhook delivers post-commit artifact-creation events to configured HTTP targets (outbound webhooks).
pat Package pat implements Cairn's personal access tokens: human-minted bearer credentials for the /v1 surface, created and revoked from the web Settings UI (issue #74).	Package pat implements Cairn's personal access tokens: human-minted bearer credentials for the /v1 surface, created and revoked from the web Settings UI (issue #74).
session Package session is Cairn's minimal server-side web session store (SPEC-0001, ADR-0004).	Package session is Cairn's minimal server-side web session store (SPEC-0001, ADR-0004).
sharetype Package sharetype is the compile-time share-type registry: the one place a stored share type is mapped to its viewer/panel/anchor affordances.	Package sharetype is the compile-time share-type registry: the one place a stored share type is mapped to its viewer/panel/anchor affordances.
store Package store is the Artifact core service: it streams bodies into content-addressed object storage and persists the Artifact aggregate and its blob registry in Postgres, transactionally.	Package store is the Artifact core service: it streams bodies into content-addressed object storage and persists the Artifact aggregate and its blob registry in Postgres, transactionally.
trajectory Package trajectory is the core service for the trajectory share type: it persists an agent run as an ordered, nested span tree, spills oversized span outputs to content-addressed object storage, links a run to the artifacts it produced, and derives all run statistics from the span rows so they can never disagree with the waterfall.	Package trajectory is the core service for the trajectory share type: it persists an agent run as an ordered, nested span tree, spills oversized span outputs to content-addressed object storage, links a run to the artifacts it produced, and derives all run statistics from the span rows so they can never disagree with the waterfall.
webhook Package webhook is the core service for the webhook (requestbin) share type: it provisions a capture endpoint as an ordinary Cairn artifact, holds its captured requests in a bounded, seq-ordered ring buffer — metadata in PostgreSQL, oversized bodies spilled to content-addressed object storage — and evicts the oldest record whenever a capture would push the buffer past its cap.	Package webhook is the core service for the webhook (requestbin) share type: it provisions a capture endpoint as an ordinary Cairn artifact, holds its captured requests in a bounded, seq-ordered ring buffer — metadata in PostgreSQL, oversized bodies spilled to content-addressed object storage — and evicts the oldest record whenever a capture would push the buffer past its cap.