Skip to content
Agent Detective

Golden path — first analysis

Golden path — first analysis

Section titled “Golden path — first analysis”

Two milestones on the way to production:

MilestoneTimeJira account?Guide
Local mock smoke~5 minNoGet started
Real Jira webhook~15 minYesThis page

Complete get started first (agent-detective smoke → [MOCK] Added comment in logs). Then wire Jira through a tunnel.

Target outcome (real Jira)

Section titled “Target outcome (real Jira)”
  • agent-detective doctor passes — see CLI reference — doctor.
  • Server answers GET /api/health on your port.
  • A Jira (or Automation) webhook reaches your server through HTTPS (tunnel or reverse proxy).
  • With mockMode: true, logs show [MOCK] Added comment after an issue with a matching repo label.
  • With mockMode: false, a real comment appears on the issue (allow time for API credentials).

Deep detail: jira-manual-e2e.md.

Prerequisites

Section titled “Prerequisites”
RequirementNotes
Node.js 24+npm: npm i -g agent-detective. Contributors: pnpm 10+ — development.md.
git on PATHlocal-repos plugin reads your checkout.
Agent CLI (OpenCode, Cursor, …)Match config.agent; authenticated for real analysis.
Git clone on diskrepos[].name must match a Jira label (case-insensitive).
Jira CloudWebhooks or Automation → Send web request.
Tunnel (ngrok, Cloudflare Tunnel, …)Jira needs HTTPS to your host.

Steps (real Jira)

Section titled “Steps (real Jira)”

  1. Install and scaffold (if not done)

    Terminal window
    npm i -g agent-detective
    mkdir -p ~/agent-detective && cd ~/agent-detective
    agent-detective init --yes --repo-path /absolute/path/to/checkout --repo-name my-app
    agent-detective doctor --config-root .

    Contributors from a git clone: pnpm install, copy config/local.example.json → config/local.json, pnpm run dev.

  2. Local smoke (optional but recommended)

    Terminal window
    agent-detective --config-root .   # terminal 1
    agent-detective smoke --config-root .   # terminal 2

  3. Run the server (if not already)

    Terminal window
    agent-detective --config-root .

  4. Tunnel — expose http://127.0.0.1:<port> (default 3001) as public HTTPS.

  5. Jira webhook

    • URL: https://<tunnel-host>/plugins/agent-detective-jira-adapter/webhook/jira
    • Events: Issue created, Comment created (retry path).
    • Automation without webhookEvent in the body: add ?webhookEvent=jira:issue_created — see jira-manual-e2e.md.

  6. Create a Jira issue with a label equal to your repo name.

  7. Verify — logs: webhook → queued → agent → comment ([MOCK] or real).

Reference layout

Section titled “Reference layout”
flowchart LR
  subgraph internet [Internet]
    Jira[Jira_Cloud]
  end
  subgraph host [Your_host]
    T[Tunnel_client]
    AD[agent-detective]
    R[Git_clone]
    A[Agent_CLI]
  end
  Jira -->|HTTPS_webhook| T
  T --> AD
  AD --> R
  AD --> A

Production nginx TLS: deployment.md.

Troubleshooting

Section titled “Troubleshooting”
SymptomWhat to check
Webhook never hits serverTunnel URL, Jira rule history, firewall, correct POST path under /plugins/....
400/404 on webhookPlugin loaded (doctor, startup logs); path matches Jira adapter route.
No analysisIssue labels match repos[].name — matching docs.
suppressing auto-analysis … cooldownNormal echo guard; wait or use explicit retry comment.
Agent failsAgent on PATH, LLM credentials, config.agent id.
Real comment failsmockMode: false + JIRA_* env — configuration.md.

Next steps

Section titled “Next steps”

Support matrix: root README.md.