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 .
# another terminal, server running:
agent-detective smoke --config-root .

Five-minute walkthrough: Get started. Real Jira + tunnel: Golden path. Commands: CLI reference. 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 · CLI reference · 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

• CLI reference — init, doctor, smoke, validate-config

• 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.