██╗  ██╗  ██████╗  ██╗   ██╗ ███╗   ██╗ ██████╗         ████████╗ ██████╗   █████╗    ██████╗  ███████╗ ██████╗
██║  ██║ ██╔═══██╗ ██║   ██║ ████╗  ██║ ██╔══██╗        ╚══██╔══╝ ██╔══██╗ ██╔══██╗  ██╔════╝  ██╔════╝ ██╔══██╗
███████║ ██║   ██║ ██║   ██║ ██╔██╗ ██║ ██║  ██║ █████╗    ██║    ██████╔╝ ███████║  ██║       █████╗   ██████╔╝
██╔══██║ ██║   ██║ ██║   ██║ ██║╚██╗██║ ██║  ██║ ╚════╝    ██║    ██╔══██╗ ██╔══██║  ██║       ██╔══╝   ██╔══██╗
██║  ██║ ╚██████╔╝ ╚██████╔╝ ██║ ╚████║ ██████╔╝           ██║    ██║  ██║ ██║  ██║  ╚██████╗  ███████╗ ██║  ██║
╚═╝  ╚═╝  ╚═════╝   ╚═════╝  ╚═╝  ╚═══╝ ╚═════╝            ╚═╝    ╚═╝  ╚═╝ ╚═╝  ╚═╝   ╚═════╝  ╚══════╝ ╚═╝  ╚═╝

Hound Tracer converts raw failure evidence into a structured investigation: failure classification, cited evidence, root-cause hypotheses, triage, recommended checks, and a reviewable ticket draft. It reads plain logs, JUnit XML, SARIF, and supported test-report JSON.

The deterministic engine works offline. LLM analysis, repository source context, deployment enrichment, and external ticket delivery are separate capabilities that you enable explicitly.

See the result

This excerpt comes from an offline report generated from a failing Cargo test in demo-output:

Failure
  Stage: test
  Kind: test_failure
  Summary: test totals::adds_tax ... FAILED

Root cause
  Hypothesis: Test assertion failed; the code under test diverges from expectations.
  Confidence: medium
  Evidence score: 0.75
  Support status: supported

Evidence
  Failed test: totals::adds_tax
  Location: src/totals.rs:13
  Assertion: left 10, right 11

Triage
  Severity: medium
  Component: src
  Priority: 3

Each analysis writes:

run-<id>/
├── report.json   # RCA Document Schema v2.0 for automation
├── report.md     # investigation for humans
└── ticket.md     # reviewable issue draft

The complete contract includes evidence provenance, hypotheses, missing information, recommended checks, timeline data, source impact, recurrence, engine status, fallback reason, and cost information. See the architecture guide and RCA JSON Schema.

How it works

Failure evidence
  .log · JUnit XML · SARIF · supported test-report JSON
       │
       ▼
Ingest
  bounded reads · stack framing · test parsing · redaction
       │
       ▼
Context, when enabled
  Git diff/blame · CODEOWNERS · source lines · deployment signals
       │
       ▼
Root-cause analysis
  reviewed cache → optional LLM → deterministic fallback
  schema validation · evidence-reference validation · budgets
       │
       ▼
Triage and output
  severity · component · fingerprint · recurrence · ticket draft

The CLI, TUI, HTTP service, GitHub Action, and MCP server call the same application service and analysis pipeline.

Install

Hound supports CPython >=3.10,<3.14. Windows and Linux are tested. macOS is expected to be portable, but release-runner evidence is still pending. See the support matrix.

Linux, macOS, or WSL

curl -fsSL https://raw.githubusercontent.com/youthisss/hound-tracer/main/install.sh | sh

The installer uses uv tool, installs uv when it is missing, and verifies the resulting hound executable.

Windows (native PowerShell)

Native Windows runs the CLI, TUI, service, and MCP server without WSL. Run this in PowerShell:

iex (irm https://raw.githubusercontent.com/youthisss/hound-tracer/main/install.ps1)

Close applications that are running hound or hound-mcp before upgrading. Windows locks active executables; the installer stops before making changes when it detects a running Hound process.

uv tool, recommended

uv tool install hound-tracer
hound --version
hound doctor

Running either installer again upgrades the existing uv tool installation. To install a specific release, set HOUND_VERSION first.

pipx or pip

pipx install hound-tracer

# Or inside an existing Python environment
python -m pip install hound-tracer

Source checkout

git clone https://github.com/youthisss/hound-tracer.git
cd hound-tracer
uv sync --extra dev
uv run hound doctor

Installed entry points:

• hound opens the launcher or runs a CLI command.
• hound-mcp starts the stdio MCP server for coding-agent clients.

Quick start

Analyze an existing failure

hound analyze failure.log --offline

Hound writes report.json, report.md, and ticket.md under hound-output/. Offline mode makes no provider request.

Capture and analyze a command

hound log --analyze --offline -- pytest -q

The command output is redacted while it is captured. Hound preserves the wrapped command's exit code and analyzes the capture when requested.

Initialize a project workspace

hound init
hound doctor
hound analyze --offline

hound init creates .hound.yml and an idempotent .hound/ workspace for artifacts, captures, project runs, results, and local state. An existing configuration is preserved.

Common workflows

Add source and Git evidence

hound analyze ./ci-logs \
  --repo-dir . \
  --source-context \
  --offline

Source context is opt-in and intended for trusted checkouts. It can add bounded snippets, diff context, blame, commit subjects, CODEOWNERS, and advisory test-impact information.

Process a directory with bounded model usage

hound batch \
  --logs ./ci-logs \
  --output-dir ./batch-output \
  --jobs 8 \
  --max-llm-calls 50 \
  --max-cost-usd 5.00

When a call or cost budget is exhausted, remaining artifacts use deterministic fallback and record budget_skipped.

Build test history and evaluate a quality gate

hound insights import ./junit.xml \
  --test-runner pytest \
  --branch main \
  --commit abc1234 \
  --environment "os=linux;python=3.11"

hound gate ./test-results \
  --repo-dir . \
  --baseline-ref origin/main \
  --candidate-ref HEAD \
  --policy ./quality-gate.yml \
  --coverage ./coverage/coverage.json \
  --sarif ./reports/semgrep.sarif \
  --output gate-results.json

The local SQLite history store tracks outcomes, durations, branches, commits, and environments. Gate policies can evaluate new failures, flakiness, coverage delta, changed-line coverage, severity, and SARIF findings.

Run in GitHub Actions

- name: Run tests
  id: tests
  continue-on-error: true
  run: pytest --junitxml=artifacts/junit.xml | tee artifacts/pytest.log

- name: Investigate failure
  if: steps.tests.outcome == 'failure'
  uses: youthisss/hound-tracer@v0.8.0
  with:
    log: artifacts/pytest.log
    repo: ${{ github.workspace }}
    out: ${{ github.workspace }}/hound-output
    offline: "true"

- name: Upload report
  if: steps.tests.outcome == 'failure'
  uses: actions/upload-artifact@v4
  with:
    name: hound-report
    path: hound-output/

Action paths must stay under GITHUB_WORKSPACE. The GitHub Action guide documents inputs, outputs, permissions, and upgrades.

Run with Docker

docker build -t hound-tracer .
docker run --rm \
  -v "$PWD/ci-logs:/logs:ro" \
  -v "$PWD/hound-output:/out" \
  hound-tracer analyze /logs --output-dir /out --offline

The release image runs the main Hound process as a non-root user.

Interfaces

Terminal UI

hound console --logs ./ci-logs --offline

The Textual UI has Home, Artifacts, Project Runs, Results, and Quality workspaces. Stored runs expose Overview, Report, Ticket, Context, and Raw log views. The Run project action requires confirmation and uses a bounded timeout and output capture, but the invoked project remains unsandboxed.

HTTP service

export HOUND_SERVER_TOKEN="replace-with-a-long-random-token"

hound serve \
  --host 127.0.0.1 \
  --port 8123 \
  --log-root ./ci-logs \
  --output-dir ./server-runs

The service binds to loopback, uses Bearer authentication, and persists its queue in SQLite. It provides job submission, inspection, cancellation, health, readiness, and authenticated statistics endpoints. Put a controlled reverse proxy in front of it for TLS or remote ingress. See server deployment.

Coding agents and MCP

hound-mcp

The MCP surface exposes bounded tools for:

• artifact analysis and command capture;
• quality gates and test insights;
• incident and report inspection;
• report integrity validation;
• history transfer and engineer feedback;
• offline diagnostic evaluation.

HOUND_MCP_ROOTS confines filesystem access. HOUND_MCP_MODE selects readonly, diagnostic, write, or execute capability classes. Command execution also requires HOUND_MCP_ENABLE_COMMAND_EXECUTION=1.

Hound packages skills, plugin prompts, and MCP configuration for OpenCode V2, Hermes Agent, Claude Code, Codex, Cursor, and Antigravity:

hound install skill --for claude --scope global --yes
hound install mcp --for opencode --scope global --yes
hound install all --for claude --scope global --yes

The engine surface matrix shows what is exposed to agents and what remains internal. Harness-specific setup examples live under integrations/.

hound run --detect
hound run -- pytest -q
hound run --directory ./backend --timeout 600 -- npm test
hound run --analyze --offline -- cargo test

Analysis contract

Accepted evidence

Directory analysis is recursive. Hound prunes dependency trees, virtual environments, VCS metadata, generated results, state, common caches, and symlinked paths.

Exit codes

hound log and hound run normally preserve the wrapped command's exit code. A timeout uses 124; cancellation uses 130. Quality-gate exit codes are documented in architecture.

Supported failure areas

Hound classifies failures across build, test, CI, deployment, containers, Kubernetes, network, and TLS workflows. Stack framing covers Python, Go, Rust, Java, JavaScript and TypeScript V8 output, C and C++, C#, YAML, Terraform, and template locations. Test ingestion recognizes pytest, Jest, Vitest, Go test, RSpec, Cargo test, dotnet test, and JUnit XML.

Optional connectors collect bounded read-only Kubernetes, Helm, Prometheus, and Tempo-compatible evidence after explicit configuration and trust checks. See deployment connectors and operational correlation.

Configuration and model providers

Start with an offline project configuration:

hound init
hound config validate --config .hound.yml
hound config show

Configuration resolves in this order:

CLI flags → YAML configuration → HOUND_* environment variables
          → provider-specific environment variables → offline fallback

Hound supports built-in presets for OpenAI, Anthropic-compatible endpoints, Gemini, Groq, Ollama, DeepSeek, Azure OpenAI, 9router, and custom endpoints. It can also invoke explicitly accepted Codex, Claude Code, or Gemini CLI subscription sessions. Subscription use may conflict with provider terms or account policies, so Hound requires explicit risk acceptance.

hound providers
hound models --provider groq --refresh

Store credentials in provider environment variables or the system keyring, not in source-controlled YAML. If a provider fails, times out, exhausts retries, or returns an invalid result, Hound records the status and uses deterministic fallback unless require_llm is enabled.

llm:
  provider: gemini
  model: auto
  temperature: 0.2
  timeout: 120.0
  max_retries: 3
  max_concurrency: 4

redact: true

trust:
  source_class: local_artifact

dedup:
  backend: sqlite
  state_file: .hound/state.sqlite3
  retention_days: 90
  reuse: true
  reuse_after_occurrences: 3

Security boundary

Hound treats artifacts, repositories, model output, and external services as separate trust boundaries.

Protections built into Hound

• Offline mode makes no provider request.
• Redaction runs before supported content reaches prompts, reports, tickets, dedup snapshots, or delivery payloads.
• Artifact, command-output, provider-response, and connector reads are bounded.
• XML parsing disables external entities.
• Fork PR trust mode forces offline analysis, keeps redaction enabled, and disables source context, enrichment, and delivery.
• Output and sensitive state paths reject unsafe symlinks where applicable and use atomic persistence for critical state.
• Provider and delivery clients reject redirects, bound responses, and cap retries.
• hound clean removes only directories carrying Hound ownership markers.

Limits you must account for

• Pattern redaction cannot identify every encoded, fragmented, novel, or application-specific secret.
• Original artifacts are not rewritten and may still contain sensitive data.
• LLM output remains probabilistic after schema and evidence-reference validation.
• Command execution is not sandboxed. Child processes inherit the Hound process permissions.
• TLS, public ingress, host permissions, backup encryption, and untrusted-checkout isolation remain operator responsibilities.

Use an external container, VM, restricted account, or disposable runner when executing commands from an untrusted checkout. Read the threat model and bounded-operation limits before production deployment.

Report suspected vulnerabilities through GitHub Security Advisories, not a public issue. See SECURITY.md.

Documentation

Development

git clone https://github.com/youthisss/hound-tracer.git
cd hound-tracer
uv sync --extra dev

uv run ruff check src tests
uv run mypy src/hound
uv run pytest -m "unit and not slow" -q
uv run pytest -m integration -q
uv run pytest -m "e2e and not slow" -q
uv run pytest --cov=hound --cov-report=term --cov-fail-under=80 -q
uv run python -m hound.eval --offline --check --format json

Contributions should preserve deterministic offline behavior, default redaction, bounded operations, and clean machine-readable output. Read CONTRIBUTING.md and the dependency policy before opening a pull request.

Project status

Hound Tracer 0.8.0 is beta software. CPython 3.10, 3.11, 3.12, and 3.13 are supported. Platform evidence and external release gates are tracked in the support matrix. Releases follow Semantic Versioning and are recorded in the changelog.

License

Hound Tracer is distributed under the MIT License.