Horus

Understand what happened.

Open-source incident investigation. Horus connects Elasticsearch, Sentry, Grafana, MongoDB, Postgres, Redis (incl. BullMQ queues), Axiom logs, Shopify Admin, and source intelligence into deterministic reports — installable today.

CLI-only. Read-only against production systems. Horus never writes to your infrastructure.

Website: horus.sh · Source: github.com/meritt-dev/horus

curl -fsSL https://horus.sh/install.sh | bash
npm install -g @merittdev/horus
brew install meritt-dev/tap/horus

Homebrew tap is live through meritt-dev/tap.

What Horus does

Horus reads from your existing systems and reconstructs the incident through evidence, correlation, and ranked hypotheses.

It does not dump thousands of logs. It connects runtime signals to source context and returns a deterministic report — suspected causes (ranked), hypotheses, evidence, gaps, and next actions. Evidence before inference. Optional --ai adds an Anthropic narrative on top.

Every incident leaves evidence.

What Horus is not


Monitoring	Detects problems
Observability	Shows signals
Horus	Reconstructs what happened

Horus is not another dashboard, alerting tool, or log viewer. It sits on top of the systems you already use.

Monitoring detects. Observability shows. Horus reconstructs.

Getting started

horus init
horus connect elasticsearch   # optional runtime connectors
horus investigate "checkout latency spike"
horus investigations          # list saved IDs
horus replay <id>
horus postmortem <id>

Horus source intelligence requires a local code-graph host (the curl installer attempts to install it). Postgres is required for the audit store.

How it works

Evidence in. Explanation out.

Runtime + Source	Investigation Engine	Investigation Report
Elasticsearch · Axiom logs · Sentry errors	Correlation	Suspected causes (ranked)
Grafana metrics	Timeline	Hypotheses + confidence
MongoDB · Postgres · Redis state	Cause ranking	Evidence + gaps
BullMQ queue runtime		Next actions
Source graph + git

Pipeline: Evidence → Correlation → Hypotheses → Timeline → Report

Sources Horus investigates

Elasticsearch · Sentry · Grafana · MongoDB · Postgres · Redis · BullMQ · Axiom · Git changes · Source graph · Queue map · Ownership

Trace reconstruction is not shipped yet. Connectors are read-only and project-scoped.

Example output (illustrative)

cd ~/code/atlas-payments
horus investigate --env production "checkout latency spike"

# Investigation inv-347
Hint: checkout latency spike

## Suspected causes (ranked)
1. [0.82 / high] Redis connection pool exhaustion [↑ queue]

## Hypotheses
  [supported] [0.78] queue: backlog growth preceded latency spike

## Evidence gaps
  - queue runtime state: worker heartbeat unavailable

## Evidence
- ev-01 [elasticsearch/error] Request timeout increase
- ev-04 [bullmq/queue] checkout-jobs backlog growth

## Next actions
- Inspect worker concurrency changes in deploy #784

Principles

Read-only — Horus never writes to your production systems.

Deterministic first — The engine is deterministic; optional --ai adds an Anthropic narrative.

Local-first — Connectors read from your own clusters, not a hosted black box.

Project-scoped — The repo you run in (its .horus/config.json) is the project identity; --config <path> targets another repo.

Agent-ready — Every investigation/analysis command takes --json (compact by default, --full for the raw structure) with a nextSteps array to chain from. horus packet builds a compact, honesty-framed briefing sized for an agent's context window.

Capabilities

Installable today. More connectors and AI providers are in progress.

Today

Elasticsearch logs
Axiom logs
Sentry errors
Grafana metrics
MongoDB / Postgres / Redis state
BullMQ queue evidence
Shopify Admin (GraphQL — queries you supply)
Source intelligence (code graph)
Timeline generation
Evidence correlation
Investigation replay
Postmortem drafts

Coming next

Kubernetes evidence
Distributed trace reconstruction
Slack evidence ingestion
Local AI provider execution

Architecture

Horus is organized in four layers:

Source Intelligence

Horus source intelligence backend (packages/source-py, ships inside the bundle) — code graph, semantic search, impact analysis, ownership across TypeScript/JavaScript, Python, Go, Java, and Rust (tree-sitter).

Runtime Evidence

Elasticsearch — logs → synthesized error-signature evidence
Axiom — structured logs (APL) → synthesized error-signature evidence, same path as Elasticsearch
Sentry — grouped exceptions (issues) → same error-signature / direct-seed path as logs
MongoDB / Postgres — application/operational state
Grafana — metrics via its datasource proxy
Redis / BullMQ — cache & queue runtime state
Shopify Admin — application state via GraphQL queries you supply at investigation time (--shopify-query) or declare in config; the connector embeds none. Read-only, Client-Credentials auth.
Git — change history, ownership signals

Investigation (deterministic)

Queue Stitcher — connects producer queue.add(...) to consumer @Processor handlers
Timeline Engine — orders evidence into a sequence of events
Correlation Engine — connects evidence across sources into incident threads

Presentation

Deterministic investigation report — evidence, timeline, hypotheses, gap analysis, next actions
Optional AI narrative — a later layer on top of the deterministic report

Source intelligence is built into Horus

Source intelligence is the expected intelligence layer used by Horus — not an optional integration. Semantic search, impact analysis, ownership signals, change detection, and the process graph live in the Horus source intelligence backend; Horus does not duplicate them.

The only code-intelligence gap Horus owns is queue-boundary stitching: the source graph terminates around queue.add(...) and doesn't connect a producer to the consumer's @Processor. The stitcher synthesizes those producer → queue → worker edges.

If the Horus source intelligence backend is unavailable, Horus can still collect runtime evidence, but source context, impact analysis, change analysis, and queue stitching become degraded.

Horus talks to the source intelligence backend over HTTP/MCP only (no CLI shell-outs for queries). Run horus init in a repository to start and register its source intelligence host.

Configuration

The config model separates code from runtime:

Code belongs to the project — repositories[], each served by its own source intelligence host.
Runtime belongs to the environment — environments[].connectors (Elasticsearch, Sentry, MongoDB, Postgres, Grafana, Redis/BullMQ, Axiom).

// config/horus.config.ts
export default defineConfig({
  projects: [
    {
      name: 'atlas-payments',
      repositories: [
        {
          name: 'atlas-payments',
          path: '/repos/atlas-payments',
          source: { hostUrl: 'http://127.0.0.1:8420' },
        },
      ],
      environments: [
        {
          name: 'production',
          readOnly: true,
          connectors: {
            elasticsearch: {
              indexPattern: 'atlas-payments-prod-*',
              serviceName: 'atlas-payments-prod',
            },
            mongodb: {
              database: 'atlas_payments_prod',
              collections: ['orders', 'payments', 'workers'],
            },
            grafana: {},
          },
        },
      ],
    },
  ],
});

Local persistence is embedded (a bundled pglite database at ~/.horus/horus.db) — no database to run or configure. Teams that need shared state use Horus Cloud (an API mirror), not a self-run Postgres.

No connector runs without an explicit project/env scope — there are no global connector defaults.

Secrets are never committed. horus connect encrypts connector credentials at rest into .horus/secrets.local.json (AES-256-GCM, never config.json) and auto-adds .horus/ to .gitignore; environment variables are also supported at runtime. For the full secrets and gitignore model, see horus.sh/docs/security.

Install

See horus.sh/docs/installation for full install, update, and uninstall instructions.

curl -fsSL https://horus.sh/install.sh | bash
npm install -g @merittdev/horus
brew install meritt-dev/tap/horus
horus --version
horus init

The curl installer downloads the Horus CLI from GitHub Releases and installs the source intelligence backend from the wheel bundled in the same release — one bundle, one version, nothing on PyPI. All three channels ship the same horus binary with the backend wheel alongside it; horus init installs the backend automatically when it's missing.

What the installer installs

Component	Role	Required
Horus CLI	The `horus` command	Yes
Horus source intelligence backend	Enables `horus init`, `horus explain`, `horus changes`, `horus architecture`	Optional

Prerequisites

Requirement	Role
Node.js 22+	Horus CLI runtime (the installed binary needs Node.js)
Python 3.11+ + uv/pip	Required only for the Horus source intelligence backend

The investigation audit store is embedded (bundled pglite, zero setup) — there is no Postgres to install. Teams that need shared state use Horus Cloud.

The installer does not configure Elasticsearch, MongoDB, Grafana, Redis, or any production system. Runtime connectors are added per-project after install via horus connect.

Direct download (without the curl installer)

# Replace vX.Y.Z with the current release tag (see github.com/meritt-dev/horus/releases)
curl -fsSL https://github.com/meritt-dev/horus/releases/download/vX.Y.Z/horus-vX.Y.Z -o horus
chmod +x horus
sudo mv horus /usr/local/bin/horus
horus --version

To update to a newer version, re-run the installer — it overwrites the binary and leaves your config untouched. To uninstall, see horus.sh/docs/installation#uninstall.

If something goes wrong after install, run horus doctor and see horus.sh/docs/installation#troubleshooting.

Local development

pnpm install
pnpm build                            # builds apps/horus/dist/index.cjs

# Per repository: start the source intelligence host and stitch queue boundaries
horus init

source ~/.horus.env

node apps/horus/dist/index.cjs status

Verify the full v0.1 user path (init → investigate → replay → postmortem):

# No-services startup check (version, help, doctor):
./scripts/smoke-test.sh apps/horus/dist/index.cjs

# Full end-to-end flow (uses the embedded pglite store — no services to start):
./scripts/e2e-smoke.sh apps/horus/dist/index.cjs

horus --help
horus help <command>
horus investigate --help

Core commands

Command	What it does
`horus status [--env]`	Per-project/env connector-health matrix
`horus connect <type>`	Add/update a runtime connector — `elasticsearch` / `mongodb` / `postgres` / `sentry` / `axiom` / `grafana` / `redis` (plus `ai` to configure an AI provider)
`horus init [--env <e>]`	Set up the current repo: config, source-intelligence host, index, queue map
`horus hosts [--reap]`	List source-intelligence hosts and live status; `--reap` stops orphaned hosts
`horus stop [--all]`	Stop this repo's source-intelligence host (`--all` stops every host)
`horus investigate --env <e> "<hint>"`	Full deterministic investigation report (`--format json` for agents)
`horus packet <hint\|savedId> [--for claude] [--json]`	Compact, honesty-framed briefing for a coding-agent context window
`horus logs [service] --env <e>`	Error-signature evidence (`--raw` for lines)
`horus state --env <e>`	MongoDB application-state evidence (read-only)
`horus metrics [hint] --env <e>`	Grafana metrics evidence
`horus queues [name] [--live]`	Queue topology from source intelligence; `--live` reads real-time Redis/BullMQ state
`horus search <query>` · `explain <symbol>` · `blast-radius` · `architecture` · `what-changed`	Source-aware code intelligence — one canonical resolver, so a query resolves to the same symbol across commands (qualified `Class.method` supported)
`horus memory <show\|add\|list\|link\|...>`	Inspect/author deterministic incident memory; `memory link` adds `supersedes` / `contradicts` / `recurs-with` edges
`horus feedback <id> [--resolved] [--note] [--cause]`	Record outcome feedback on an investigation (improves Horus)
`horus report [hint] [--title --body --labels]`	File a Horus bug or capability gap — opens a pre-filled GitHub issue (no auth, nothing sent automatically)

Local project workflow (git-style)

A repo carries a .horus/config.json (discovered by walking up from the working directory, like .git) — the repo's config IS the project identity. Work from inside the repo, or pass --config <path> to target another repo explicitly.

cd /repos/atlas-payments
horus init

horus investigate "checkout latency spike"
horus investigate --config /repos/atlas-payments/.horus/config.json "checkout latency spike"   # from anywhere
horus projects   # list registered repos (informational)

horus init reuses an already-running source intelligence host when one is healthy. Runtime connectors are added to the env block of .horus/config.json afterwards.

For coding agents

Horus is built to be an agent's evidence layer. Install a skill that teaches your agent to reach for Horus before guessing:

horus skill install claude    # .claude/skills/horus/SKILL.md  (also: codex · gemini · cursor · generic)
horus mcp                     # expose the local knowledge index to agents over MCP (stdio)

Every investigation/analysis command takes --json (--format json for investigate/replay) — compact by default, --full for the raw structure — and each result carries a deterministic nextSteps array. horus packet "<hint>" --json returns a compact briefing sized for a context window.

Layout

packages/
  core/         evidence model, config schema + project/env resolution, version pins
  connectors/   provider contracts + source intelligence (HTTP/MCP) · Elasticsearch · Sentry · Axiom · Grafana · MongoDB · Postgres · Redis · BullMQ · application-state · Git
  stitcher/     queue-boundary stitcher
  db/           Drizzle schema + migrations (plain Postgres, no pgvector)
  engine/       deterministic investigation pipeline (timeline, correlation, hypotheses, gaps)
  cli/          commander CLI
apps/horus/     composition root (bundled bin)
config/         horus.config.ts

Foundation

TypeScript monorepo (pnpm + Turborepo)
Postgres + Drizzle — semantic search delegated to source intelligence backend
Built-in Horus source intelligence backend, over HTTP/MCP only
Project/environment-scoped connectors; read-only against production

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
apps/horus		apps/horus
config		config
docs		docs
homebrew-tap		homebrew-tap
packages		packages
scripts		scripts
.gitignore		.gitignore
.npmrc		.npmrc
.prettierrc		.prettierrc
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
turbo.json		turbo.json

Navigation Menu

Uh oh!

Repository files navigation

Horus

What Horus does

What Horus is not

Getting started

How it works

Sources Horus investigates

Example output (illustrative)

Principles

Capabilities

Architecture

Source intelligence is built into Horus

Configuration

Install

What the installer installs

Prerequisites

Direct download (without the curl installer)

Local development

Core commands

Local project workflow (git-style)

For coding agents

Layout

Foundation

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Horus

What Horus does

What Horus is not

Getting started

How it works

Sources Horus investigates

Example output (illustrative)

Principles

Capabilities

Architecture

Source intelligence is built into Horus

Configuration

Install

What the installer installs

Prerequisites

Direct download (without the curl installer)

Local development

Core commands

Local project workflow (git-style)

For coding agents

Layout

Foundation

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages