omnidevx

README

OmniDevX Core

Core interfaces and canonical types for OmniDevX — the PlexusOne developer-experience telemetry domain. OmniDevX collects and normalizes events from AI coding agents and development tools so frameworks such as SPACE, AI SPACE, and DORA can be computed over one vendor-neutral event model.

Not OmniDXI. omnidxi is Digital Experience Intelligence — a facade over product-analytics platforms (Amplitude, Mixpanel, Heap, Pendo). OmniDevX observes how developers and AI agents build software. The two domains are unrelated.

Layout

• Root package omnidevx — canonical Event IR, Collector contract, periods, provenance.
• store — JSONL event store (~/.plexusone/omnidevx/data/), idempotent writes, period/product-scoped reads.
• identity — resolves GitHub usernames, hashed git emails, and device-scoped local accounts to a canonical personId.
• report — builds DeveloperPeriodReport (omnidevx.developer-period/v1) from stored events: daily summaries, weekly/monthly rollups, combined + bySource metrics, coverage scoring.
• providers/claudecode — thin provider reading Claude Code local session history (~/.claude/projects/). Stdlib only.
• providers/git — thin provider emitting devx.change.committed from local git history, with AI co-author attribution. Built on grokify/gogit.
• providers/genericotel — OTLP/JSON metrics receiver for tools without a dedicated provider.

Thick providers with heavy dependencies live in vendor repos, e.g. the Codex CLI collector in omni-openai/omnidevx (requires a SQLite driver) and the GitHub contribution collector in omni-github/omnidevx (REST + GraphQL).

Privacy

Canonical events carry metadata only — event types, durations, counts, models, token figures, and repository identifiers. Prompt text, model responses, and file contents are never captured by default.

Usage

collector, err := claudecode.New(claudecode.Options{})
if err != nil {
    // handle
}
result, err := collector.Collect(ctx, omnidevx.CollectRequest{
    Period:  omnidevx.Period{Start: weekStart, End: weekEnd},
    Subject: omnidevx.SubjectRef{PersonID: "person:jane"},
})

Provenance on every event records the collection mode (history, otel, hooks, api, survey) and a confidence score, so downstream metrics can distinguish observed values from historical reconstruction.

Period reports

s, _ := store.Open(store.Options{})
read, err := s.Read(ctx, store.Query{Period: period})

r := report.Build(read.Events, report.Subject{PersonID: "person:jane"}, period)
// r.Metrics.Combined["commits"], r.Metrics.BySource["git/git"]["commits"], ...
// r.Sources, r.Quality.CoverageScore

report.Build is reproducible: the same stored events always produce the same report, and reprocessing with a changed metric formula never requires recollection. See Period Reports for the combined-vs-bySource rules and Identity for resolving multiple accounts to one person.

Specifications

Ecosystem PRD/TRD/PLAN/ROADMAP currently reside in devfolio/docs/specs and will migrate here.

License

MIT

Documentation

Overview

Package omnidevx defines the canonical intermediate representation (IR) for developer-experience telemetry: events observed while developers and AI coding agents build software, and the collector contract that source providers implement.

OmniDevX is not OmniDXI: OmniDXI (github.com/plexusone/omnidxi) is a Digital Experience Intelligence facade over product-analytics platforms (Amplitude, Mixpanel, Heap, Pendo). OmniDevX observes developer and coding-agent activity (sessions, prompts, tool calls, commits, reviews) for frameworks such as SPACE, AI SPACE, and DORA.

Privacy: canonical events carry metadata only — event types, durations, counts, models, token figures, and repository identifiers. Prompt text, model responses, and file contents are never captured by default.

Index

• Constants
• type CollectRequest
• type CollectionMode
• type CollectionResult
• type Collector
• type Diagnostic
• type Event
• type EventContext
• type EventType
• type Period
  • func (p Period) Contains(t time.Time) bool
• type Provenance
• type Source
• type SubjectRef

Constants

const (
	SeverityWarning = "warning"
	SeverityError   = "error"
)

Diagnostic severities.

const (
	AttrModel               = "model"
	AttrInputTokens         = "input_tokens"
	AttrOutputTokens        = "output_tokens"
	AttrCacheReadTokens     = "cache_read_tokens"
	AttrCacheCreationTokens = "cache_creation_tokens"
	AttrReasoningTokens     = "reasoning_tokens"
	AttrTotalTokens         = "total_tokens"
	AttrTool                = "tool"
	AttrSuccess             = "success"
	AttrDurationMS          = "duration_ms"
	AttrTimeToFirstTokenMS  = "time_to_first_token_ms"
	AttrSidechain           = "sidechain"
	AttrClientVersion       = "client_version"
	AttrReasoningEffort     = "reasoning_effort"
	AttrSessionSource       = "session_source"
	AttrSessionTotalTokens  = "session_total_tokens"
	AttrCommitHash          = "commit_hash"
	AttrAuthorEmail         = "author_email"
	AttrAIAssisted          = "ai_assisted"
	AttrAITools             = "ai_tools"
	AttrInsertions          = "insertions"
	AttrDeletions           = "deletions"
	AttrFilesChanged        = "files_changed"
	AttrCommits             = "commits"
	AttrContributions       = "contributions"
	AttrPullRequests        = "pull_requests"
	AttrIssues              = "issues"
	AttrReviews             = "reviews"
	AttrRepositories        = "repositories"
	AttrReposCreated        = "repos_created"
	AttrReleases            = "releases"
	AttrPrivateRepo         = "private"
	AttrCostUSD             = "cost_usd"
)

Common attribute keys used in Event.Attributes. Providers should prefer these keys over ad-hoc names so metrics can be computed across sources.

Types

type CollectRequest

type CollectRequest struct {
	Period  Period     `json:"period,omitzero"`
	Subject SubjectRef `json:"subject,omitzero"`
}

CollectRequest scopes a collection run. The Subject, when set, is stamped onto every event the collector emits.

type CollectionMode

type CollectionMode string

CollectionMode describes how an event was obtained.

const (
	ModeHistory CollectionMode = "history" // reconstructed from local session records
	ModeOTel    CollectionMode = "otel"    // observed via OpenTelemetry export
	ModeHooks   CollectionMode = "hooks"   // observed via lifecycle hooks
	ModeAPI     CollectionMode = "api"     // fetched from a service API
	ModeSurvey  CollectionMode = "survey"  // self-reported by the developer
)

type CollectionResult

type CollectionResult struct {
	Source      Source       `json:"source"`
	Subject     SubjectRef   `json:"subject,omitzero"`
	Period      Period       `json:"period,omitzero"`
	Events      []Event      `json:"events"`
	Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
	CollectedAt time.Time    `json:"collectedAt"`
}

CollectionResult is the output of one collection run.

type Collector

type Collector interface {
	Source() Source
	Collect(ctx context.Context, req CollectRequest) (*CollectionResult, error)
}

Collector is implemented by every source provider. Implementations normalize provider-native records into canonical events; they never compute framework metrics.

type Diagnostic

type Diagnostic struct {
	Severity string `json:"severity"`
	Message  string `json:"message"`
	Path     string `json:"path,omitempty"`
}

Diagnostic reports a non-fatal problem encountered during collection, such as an unparseable record. Collectors surface these rather than silently dropping data.

type Event

type Event struct {
	ID         string         `json:"id"`
	Type       EventType      `json:"type"`
	Timestamp  time.Time      `json:"timestamp"`
	Subject    SubjectRef     `json:"subject,omitzero"`
	Source     Source         `json:"source"`
	Context    EventContext   `json:"context,omitzero"`
	Attributes map[string]any `json:"attributes,omitempty"`
	Provenance Provenance     `json:"provenance"`
}

Event is the canonical observation. IDs are deterministic per source record so re-importing the same history deduplicates naturally.

Attributes hold metadata only: never prompt text, model responses, or file contents.

type EventContext

type EventContext struct {
	SessionID  string `json:"sessionId,omitempty"`
	Repository string `json:"repository,omitempty"`
	Workspace  string `json:"workspace,omitempty"`
	GitBranch  string `json:"gitBranch,omitempty"`
}

EventContext situates an event in a session and a workspace.

type EventType

type EventType string

EventType identifies the kind of activity an Event records.

The "ai." namespace covers coding-agent session activity; the "devx." namespace covers development-work semantics (commits, reviews, delivery).

const (
	EventSessionStarted  EventType = "ai.session.started"
	EventSessionEnded    EventType = "ai.session.ended"
	EventPromptSubmitted EventType = "ai.prompt.submitted"
	// EventMessageCompleted records one assistant turn, with model and
	// token-usage attributes.
	EventMessageCompleted EventType = "ai.message.completed"
	EventToolCompleted    EventType = "ai.tool.completed"
	EventPatchApplied     EventType = "ai.patch.applied"
	EventTaskStarted      EventType = "ai.task.started"
	EventTaskCompleted    EventType = "ai.task.completed"
	// EventUsageRecorded reports incremental token usage for sources that
	// emit usage separately from assistant messages.
	EventUsageRecorded EventType = "ai.usage.recorded"
)

Coding-agent session event types.

const (
	// EventChangeCommitted records one git commit, with attribution
	// attributes including AI co-author detection.
	EventChangeCommitted EventType = "devx.change.committed"
	// EventContributionRecorded is one calendar day of platform-reported
	// contribution activity (e.g. the GitHub contribution graph).
	EventContributionRecorded EventType = "devx.contribution.recorded"
	// EventContributionSnapshot is a per-repository contribution summary
	// observed for a period.
	EventContributionSnapshot EventType = "devx.contribution.snapshot"
	// EventProfileSnapshot is a whole-profile contribution summary observed
	// for a period.
	EventProfileSnapshot EventType = "devx.profile.snapshot"
)

Development-work event types ("devx." namespace).

type Period

type Period struct {
	Start time.Time `json:"start,omitzero"`
	End   time.Time `json:"end,omitzero"`
}

Period is a half-open time range [Start, End). A zero Start or End leaves that bound open.

func (Period) Contains

func (p Period) Contains(t time.Time) bool

Contains reports whether t falls within the period.

type Provenance

type Provenance struct {
	CollectionMode CollectionMode `json:"collectionMode"`
	Confidence     float64        `json:"confidence"`
}

Provenance records how an event was collected and how reliable it is. Confidence is in [0, 1]; directly observed events are 1.0, historical reconstruction is lower.

type Source

type Source struct {
	Provider string `json:"provider"`
	Product  string `json:"product"`
	Version  string `json:"version,omitempty"`
}

Source identifies the system an event came from. Provider and Product use canonical names (e.g. provider "anthropic", product "claude-code") even when Go package names are compressed.

type SubjectRef

type SubjectRef struct {
	PersonID     string `json:"personId,omitempty"`
	LocalAccount string `json:"localAccount,omitempty"`
	DeviceID     string `json:"deviceId,omitempty"`
}

SubjectRef identifies whose activity an event describes. PersonID is the canonical identity; account fields support later identity resolution.