Agent Detective

AI-powered code analysis agent that responds to events from Jira, Telegram, Slack and more.

Concept

When a new incident is created in Jira, this agent analyzes the relevant repository to identify possible causes and writes a detailed comment to help developers resolve it.

Architecture

Core agent logic is source-agnostic — plugins normalize events from different sources (Jira, Telegram, Slack) into a common format.

Run it (npm)

Install on a host where your agent CLI (OpenCode, Cursor, Claude) is already on PATH and authenticated:

npm i -g agent-detective
mkdir -p ~/agent-detective && cd ~/agent-detective
agent-detective init --repo-path /absolute/path/to/your/git/checkout --repo-name symfony
agent-detective doctor --config-root .
agent-detective --config-root .

Five-minute walkthrough with a mock Jira webhook (no Jira account): Get started. Full Jira + tunnel: Golden path. Production VM: Deployment.

Develop it (pnpm)

Clone the monorepo when you change core code or plugins:

git clone https://github.com/andezdev/agent-detective.git
cd agent-detective
pnpm install
pnpm dev

CI runs pnpm build (packages) and pnpm run build:app (root dist/). See Development Guide.

Packages

| Package | Description | |---------|-------------| | Root app | Fastify server (src/, not under packages/) | | @agent-detective/types | Host-internal type-only contract package (re-exported through @agent-detective/sdk; plugins should not depend on it directly) | | @agent-detective/sdk | Plugin-author SDK — single dependency for plugins. Bundles defineRoute, registerRoutes, definePlugin, zodToPluginSchema, service-name constants (REPO_MATCHER_SERVICE, PR_WORKFLOW_SERVICE), StandardEvents, and re-exports every plugin-facing type from @agent-detective/types | | @agent-detective/observability | Logging, metrics, health | | @agent-detective/process-utils | Process / shell helpers | | @agent-detective/local-repos-plugin | Local repositories + RepoMatcher | | @agent-detective/jira-adapter | Jira webhook adapter | | @agent-detective/linear-adapter | Linear webhooks + OAuth, signature verification, deduplication; posts analysis back on task completion (E2E) |

Configuration

Start with docs/config/configuration-hub.md (load order and top-level keys), then docs/config/configuration.md for the full env and plugin tables, docs/reference/generated/app-config.md for the top-level app schema (Zod/JSON), and docs/reference/generated/plugin-options.md for bundled plugin fields.

Configure via config/default.json (and optional config/local.json):

{
  "port": 3001,
  "agent": "opencode",
  "plugins": [...]
}

Operator docs: Get started · Installation paths · Upgrading · Threat model

Support matrix

| Dimension | Supported / tested in CI (typical) | Notes | |-----------|--------------------------------------|--------| | Runtime | Node.js 24+; npm CLI agent-detective | See package.json engines / packageManager. | | Host OS | Linux for production guides (systemd + nginx) | macOS/Windows OK for dev; WSL acceptable for local smoke. | | HTTP server | Fastify on configurable port (default 3001) | /api/health, /api/metrics, Scalar /docs. | | Agent CLIs | OpenCode documented; Claude / Cursor agent ids registered in-repo | Match config.agent to an installed CLI; see cursor-agent.md for Cursor. | | Jira | Jira Cloud webhooks + REST (Basic or OAuth 2.0 3LO) | Webhook + Automation shapes per jira-manual-e2e.md. Data Center not separately certified—treat as best-effort if APIs align. | | Linear | Linear webhooks + GraphQL comments (OAuth or PAT) | linear-manual-e2e.md, linear-adapter.md. | | Kubernetes / Helm | Not shipped in-repo | Bring your own container or VM; see installation.mdx. |

Documentation

• Documentation site (Starlight): pnpm run docs:site from the root builds the static site in apps/docs/ (source markdown is docs/; a sync script runs on build). Published: https://agent-detective.chapascript.dev/docs/ (GitHub Pages + custom domain in repo settings, DNS in Cloudflare). GitHub Actions is the Pages source. CI: .github/workflows/docs-site.yml.

• Get started — five-minute npm quickstart with mock webhook

• Installation — npm CLI, from source, or bare metal

• Configuration (overview) — full reference

• Upgrading — releases and upgrade runbook

• Architecture

• Extending with custom plugins — npm, paths, private registry

• Plugin development (full guide)

• Development Guide

• Jira E2E (manual walkthroughs) — webhooks, tunnel, pr-pipeline

License

This project is licensed under the MIT License - see the LICENSE file for details.