oddyssey-trailer.mp4
A CLI toolbox for Observability-Driven Development (ODD).
With APM, for Claude Code:
uvx --from 'apm-cli==0.29.1' apm install --global --target claude using-system/oddysseySame command for every other supported CLI agent — swap the target:
--target opencode, copilot, kiro, cursor, codex, gemini,
windsurf. Drop --global to install into the current repository
only.
To update an existing install to the latest version:
uvx --from 'apm-cli==0.29.1' apm update --global --target claude using-system/oddysseyIt shows the update plan and asks for confirmation (--yes to skip,
--dry-run to only look); uvx --from 'apm-cli==0.29.1' apm outdated
tells you whether an update is worth running.
Claude Code
/plugin marketplace add using-system/oddyssey
/plugin install oddyssey@oddyssey-plugin
GitHub Copilot CLI
copilot plugin marketplace add using-system/oddyssey
copilot plugin install oddyssey@oddyssey-plugin
Kimi Code
/plugin marketplace add using-system/oddyssey
/plugin install oddyssey@oddyssey-plugin
The native artifacts are generated from the APM package on every
release (marketplace/, built by scripts/build-marketplace.sh) and
carry the same agents, commands, skills, and pinned MCP server. The
other CLIs (Codex, opencode, Cursor, Windsurf, Kiro, Gemini) install
via APM above. opencode and Cursor install into the current
repository only — leave --global out.
ODD complements Spec-Driven Development: observe a running service — local or remote — through its telemetry, turn what you see into the next SDD wave (spec, plan, implement), then observe again. A continuous improvement loop, indefinitely.
Everything is built on OpenTelemetry. For local observation, the MCP server pilots a complete Grafana stack (UI, traces, metrics, logs, profiles) that agents use to observe and fix. For remote stacks, observation works against Grafana or any other OpenTelemetry backend (Datadog, Dynatrace, Azure Monitor, CloudWatch, your own, ...).
oddyssey provides:
- an OpenTelemetry expert (
otel-instrumentation-expert) that investigates your stack and hands your CLI agent everything needed to integrate OpenTelemetry and deploy collectors; - a run investigation agent (
observe-run), local or remote, that delivers a complete observation report your CLI agent turns into a spec-driven plan of fixes and improvements; - a complete local observability stack based on Grafana, piloted by the oddyssey MCP server (what it runs and on which ports);
- an ODD memory carried by the repo itself — every observation and
instrumentation report lands in
.odd/, committed and versioned with the code, shared with the whole team, and recalled as the baseline of the next run: the loop accumulates knowledge instead of starting blind.
Everything is packaged for any coding agent (APM: Claude Code, Copilot, Cursor, Codex, Gemini, and friends).
The loop in three prompts — every example below links to a real artifact from this repository: oddyssey instrumented, observed, and verified its own MCP server.
Step 1 — Instrument OpenTelemetry.
/odd-instrument-otel add OpenTelemetry to my project XXX
The otel-instrumentation-expert agent investigates the codebase,
stores its report in .odd/otel-instrumentation-reports/ (committed —
the next investigation starts from it), and hands back everything a
spec-driven wave needs. Real output of that wave on this repo: the
design spec
and the
implementation plan
generated with superpowers from
the agent's investigation report.
Step 2 — Observe a local run.
/odd-observe check that my project XXX starts and answers requests on the /user endpoint
The observe-run agent drives the run, queries the telemetry, and
stores its report in .odd/observe-run-reports/ — findings, evidence,
and the replay protocol the verification will consume. Real example: the
first observation report
(4 confirmed findings) and the
fix-wave plan
the next SDD wave built from it.
Step 3 — Verify the fixes the SDD wave delivered.
/odd-verify check that report XXX from .odd has been fixed
The same agent replays the stored report's protocol and rules on every recorded item — before-value, after-value, pass criterion. Real example: the verification report — 9/9 checks pass, all 4 findings fixed, measured not assumed.
Step 4 — Deploy and observe remotely.
Let the deployment run for a while first — a remote observation needs
real traffic history to read, not a freshly booted service. Then point
the missions at the remote stack: its CLI must be installed and
configured beforehand (gcx for a Grafana stack), and /odd-config
is the guided way to switch and prove the connection before any
mission runs. A backend the package does not ship is one
/odd-config create a stack <name> away: the file it writes lives in
your repository, and you complete it as your runs teach you.
/odd-config switch to grafana
/odd-observe what did my service XXX do over the last 24 hours?
Or in a single prompt — naming the stack in the mission switches the configuration too:
/odd-observe what did my service XXX do over the last 24 hours on my stack grafana?
The backends oddyssey manages, their associated CLI, and their switch prompt are documented in docs/guide/backends.md.
And the loop starts again: an SDD wave from the remote observation, a
local observe, a verify — and on it goes. Every step left a committed
report in .odd/; their formats — frontmatter fields, allowed values,
body structure — are documented in
docs/guide/reports.md.
/odd-status
/odd-status full picture, every finding and every trend
/odd-status where is the loop for my service XXX
/odd-status what was observed on prod for my service XXX
/odd-status where is the loop for XXX, cloned at ../XXX
/odd-status wontfix F4 of my last XXX report - port-move is rare, 14.5s accepted
/odd-status .apm is non-runtime - it is the package's prompts, never on the request path
Answers "where is the loop?" for this repository — one screen, per
service and stack: the last report, how many findings are open, fixed,
or declined, and what to do next — from the committed .odd/ history and
git alone: no backend query, nothing written. Ask for the full picture,
or scope it to a service, a stack, or an environment, to get every
finding, trend, and gap. It also records the rulings only you can
make, each with a one-sentence reason: a finding no fix will ever
address lands in .odd/decisions.md and stops counting as open, a
top-level directory or file that cannot change the service's runtime lands in
.odd/entry-classifications.md and stops being asked about — two
committed ledgers next to the reports.
/odd-instrument-bench author a load benchmark for my service XXX, p95 under 300ms
/odd-instrument-bench stress test XXX against http://localhost:8080, error rate must stay under 1%
/odd-instrument-bench update the XXX-read-heavy benchmark - the cart endpoints moved
Writes a k6 load-test benchmark for a service — a script plus a
manifest — under .odd/benchmarks/<name>/, as code you review and
commit like any other. It asks you only what a human must decide (test
type, thresholds, target, new benchmark or an update) and proposes the
load shape; a threshold the service can structurally never meet comes
back to you with the evidence instead of being persisted. It validates
the script without ever running the benchmark — running it is
/odd-observe's job: /odd-observe run .odd/benchmarks/<name>/. The
lifecycle is in docs/guide/benchmarks.md.
More invocation examples for every prompt live in docs/guide/prompts.md.
The missions query the backend your telemetry lands in, through its own CLI: the local stack (gcx), a remote Grafana (gcx), Azure Monitor (az), AWS CloudWatch and X-Ray (aws), Datadog (Pup) and Dynatrace (dtctl). Per backend — the CLI and how to install it, how to connect, what must already exist before there is anything to query, the switch prompt and what gets persisted — see docs/guide/backends.md.
You can add your own observability backend. A backend the package
does not ship becomes one file in your repository, with the same
sections as a built-in one, that /odd-config writes from the
documentation you point at, your instructions, or its own research,
and that your runs improve — or a pointer to a guide another
repository already carries. How, in
docs/guide/custom-backends.md.
When the system you observe spans several repositories — a
microservice architecture, a product shipped as several deliverables —
and you want the reports to accumulate in one place, drive oddyssey
from a dedicated observability repository rather than from each
service's own. Its .odd/ becomes the loop's memory for the whole
system — the memory lives with the system rather than with one
service's code — and a single /odd-status renders the system rather
than one service's slice.
Give that repository an AGENTS.md that lists the repositories and
their role — where each one lives, what it is, the service names its
telemetry carries. That list is the context your coding agent starts
every mission with, so it knows what the system is made of and where
to fetch the code a mission needs to read.
## Repositories
- `github.com/example-org/checkout-api` — the checkout API (`checkout`)
- `github.com/example-org/payment-worker` — the queue consumer (`payment`)
- `github.com/example-org/shared-telemetry` — the shared OTel helpers
- The system must be observable locally. Prefer a docker-compose that starts your whole stack, and mocks for the remote systems it queries — the oddyssey MCP server provides the local observability backend the telemetry lands in.
- Instrument with the expert. Bring OpenTelemetry into your
services through the
otel-instrumentation-expertagent rather than by hand. - One design loop, always the same. Every feature follows: SDD to develop it → observe a local run → fix and improve → repeat those last two steps until satisfied. Then deploy to the target environments. After some time, run a remote observation on the deployed environment's stack to seed the next SDD wave — and the loop starts again from the local run.
- Maturity spaces observation out. The time between remote observations grows as the service matures: a young service gets observed often, a stable one only when something is worth learning.
- Evidence over impressions. Every claim about a service comes from a query and its result — numbers, trace IDs, log lines — never "it seems faster".
- Cross-confirm before concluding. Never conclude from one signal what two could confirm (traces, metrics, logs, profiles); a single-signal anomaly is always labeled as such.
- The memory lives with the code. Observation reports are stored in
the observed repo under
.odd/— version that directory (do not add it to.gitignore): the reports get reviewed in PRs, shared by the whole team, and the git history reads observed → fixed → verified. - Verify by replaying, not by re-measuring differently. A fix is proven by replaying the recorded scenario identically; one changed variable invalidates the before/after comparison.
- What's missing is a finding too. Telemetry gaps — absent spans, logs without trace IDs, missing histograms — are deliverables of the observation and feed the next instrumentation wave.
- One telemetry, two consumers. The metrics, traces, and logs do not serve ODD alone: the same data feeds classic runtime observability — dashboards, alerting, incident investigation. Instrument once, and the development loop and the operation of the system read from the same source of truth.
- Agents observe, they never fix. The investigation agents only observe and report — they never modify the code directly. Their report is a universal input: feed it to any spec-driven framework for the spec-and-implement wave, turn it into JIRA tickets, or hand it to a human — what happens next stays your call.
A ranking of models on the loop's own work is kept in
.llms-benchmark/: each one observes the
same running stack through the same replayed traffic, and its report is
graded on evidence — of what it claimed, how much held up. The table
carries the findings, the cost and the duration of every run, so you can
pick on the axis that matters to you.
- Docker — runs the local observability stack (the MCP server drives it directly).
- gcx — required only when observing
a Grafana backend (the local stack, self-hosted, or Grafana Cloud):
brew install gcx, orcurl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | sh. - Other backends need their own CLI, each covered by the
observability-cli-guidesskill: Datadog (Pup), Dynatrace (dtctl), Azure Monitor (az), AWS CloudWatch/X-Ray (aws). python3— the package's skills run their scripts with it.- k6 —
needed to author a benchmark and to run one:
/odd-instrument-benchvalidates the script it writes withk6 inspectand one smoke iteration (never a benchmark run), and/odd-observeand/odd-verifyrun it. The three prompts' preflights install it on the spot when it is missing and Homebrew is available (brew install k6, no confirmation — k6 needs no account and no configuration); without Homebrew they follow the platform's non-interactive path when one exists, otherwise hand you the official steps. To install it yourself:brew install k6on macOS, the official APT/YUM repositories or a release binary on Linux, the MSI installer or a package manager on Windows — ak6on your path, which thegrafana/k6Docker image does not provide.
The loop: investigate (agents) → spec & implement (the main
agent's spec-driven workflow) → observe again — telemetry on both
ends. Each observation report is stored in the observed repo
(.odd/observe-run-reports/), versioned by git and shared with the whole
team, and becomes the baseline the next run diffs against — the loop
accumulates knowledge instead of starting blind.
Every prompt, agent, skill and hook of the package — its role, and who invokes what across them and the MCP tools — is listed in docs/guide/plugin.md.
The exact build, test, and lint commands live in
CONTRIBUTING.md — single source, matching what CI
enforces. In short: the project under src/ is a self-contained uv
project (own pyproject.toml); tests/ mirrors src/.
Issues, docs fixes, and code are welcome — see CONTRIBUTING.md for the layout, the exact build/test commands, and the PR conventions (squash titles drive the released version). Questions and ideas belong in Discussions; good first issues are waiting.