🌐 Language: English | 日本語

Your agent can spend money, leak data, and call tools before you notice. Shingan catches dangerous workflow structures before runtime.

Status: Beta. Shingan is under active development; v1.0 is targeted for late 2026 once baseline / ignore / severity-policy / PR-bot land. Not yet recommended for production-critical CI gating — informational use (continue-on-error: true) is the recommended integration mode today.

A Go-based static analyzer for AI agent workflows. It catches dangerous structures — infinite loops, unreachable nodes, missing error handlers, runaway cost paths, prompt-injection sinks, PII leak paths, code-execution from LLM output — before the workflow ever runs.

LLM orchestration is mainstream now, but the "design-time bug" detection layer is missing. Runtime observability (LangSmith / Langfuse) only tells you a thing happened after it cost you money or leaked data. n8n-only linters (FlowLint) miss everything else. Shingan inspects the workflow graph before execution, across LangGraph, CrewAI, ADK-Go, n8n, and custom JSON DSLs.

AI agents are unforgiving once they fan out: external API calls, browser automation, and code execution all leave irreversible side effects. Catching infinite loops, unreachable nodes, missing error handlers, PII leak paths, and prompt-injection sinks before deploy prevents the majority of cost blowups and incidents.

Every workflow framework reduces to the same primitive: a directed graph of nodes and edges. Shingan keeps that intermediate representation (IR) at the center of an Onion Architecture and runs 20+ rules that are framework-agnostic.

A static analyzer wins or loses on operational ergonomics (how disruptive it is to your CI), not just rule count. Honest current state:

So: today's recommended use is continue-on-error: true informational CI plus IDE feedback via the LSP. v0.9–v0.10 is closing the operational gap.

The OWASP Agentic AI Top 10 (2025) lists ten failure modes specific to agentic LLM systems. Static analysis can only catch the structural class of these — runtime observability tools (LangSmith, Langfuse) cover the rest. Today's coverage:

Roadmap to full structural coverage (everything but AAI01 / AAI05 / AAI07, which are runtime-class): v0.9 — see the v0.9 plan in shingan-adr.md.

Onion Architecture — dependencies flow inward only.

┌─────────────────────────────────────────────┐
│  cmd/          DI wiring + entry points      │
│  ┌───────────────────────────────────────┐  │
│  │  infrastructure/   concrete adapters   │  │
│  │  ┌─────────────────────────────────┐  │  │
│  │  │  application/   use cases        │  │  │
│  │  │  ┌───────────────────────────┐  │  │  │
│  │  │  │  domain/  zero external dep│  │  │  │
│  │  │  └───────────────────────────┘  │  │  │
│  │  └─────────────────────────────────┘  │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

Three Factory points

• AnalyzerFactory — registers and creates analysis rules (domain.AnalysisRule)
• ParserFactory — switches parsers by input format (application.WorkflowParser)
• ReporterFactory — switches reporters by output format (application.ReportFormatter)

The fastest way to see Shingan working — runs a bundled sample workflow through the full pipeline and prints a real findings report. No input file needed.

npx --yes shingan-lint demo
# → exit 2, surfaces loop_guard (Critical) + unreachable_node (Warning) + more

Then run it on your own workflow JSON:

# A minimal but failing workflow, written to disk and analyzed in one shot.
cat > workflow.json <<'EOF'
{
  "entry_node_id": "start",
  "nodes": [
    {"id": "start", "type": "llm",  "name": "Planner"},
    {"id": "loop",  "type": "loop", "name": "Retry Loop"},
    {"id": "step",  "type": "llm",  "name": "Worker"}
  ],
  "edges": [
    {"from": "start", "to": "loop"},
    {"from": "loop",  "to": "step"},
    {"from": "step",  "to": "loop"}
  ]
}
EOF
npx --yes shingan-lint analyze --input workflow.json --output markdown

# one-shot run (no install)
npx --yes shingan-lint demo

# project-pinned
pnpm add -D shingan-lint
pnpm exec shingan demo

# global
npm install -g shingan-lint
shingan demo

shingan-lint is a thin Node wrapper. Its postinstall step downloads the platform-specific Go binary from GitHub Releases, verifies the SHA-256 checksum, and caches it under ~/.cache/shingan-lint/v<ver>/. Linux, macOS, and Windows on amd64 / arm64 are all supported.

go install github.com/hatyibei/shingan/cmd/shingan@latest
shingan demo

git clone https://github.com/hatyibei/shingan.git
cd shingan
go build -o shingan ./cmd/shingan
./shingan demo

docker pull ghcr.io/hatyibei/shingan:latest
docker run --rm ghcr.io/hatyibei/shingan demo

JSON input (default format):

shingan analyze --input workflow.json --output markdown

ADK-Go input (directory of .go files):

shingan analyze --format adk-go --input ./agents/ --output markdown

LangGraph (Python) input — requires the analyzed project's deps to be importable:

# prerequisite: pip install langgraph   (plus whatever your project imports)
shingan analyze --format langgraph --input agent.py --output markdown
shingan analyze --format langgraph --input ./agents/ --output sarif --output-file findings.sarif

Exit codes: 0 = info-only or clean, 1 = warnings present, 2 = at least one critical.

CI integration (GitHub Actions):

- name: Shingan check
  run: shingan analyze --format adk-go --input ./agents/

Shingan is run against production LangGraph / CrewAI / n8n repos before each release. Zero Critical false positives across 12+ swept OSS at the latest release. Every Critical FP we ever surfaced has a regression fixture pinned in testdata/ and a "dogfood-driven" CHANGELOG entry.

→ Full track record + reproducible accuracy benchmark: docs/benchmarks.md.

Idioms surfaced and supported during the v0.8.5+ dogfood loop:

• Command(goto=...) and def fn() -> Command[Literal["a","b"]] typed dispatch
• add_conditional_edges("src", router_fn) with omitted path_map — router's -> Literal[...] annotation read instead
• add_conditional_edges path_map as list (["a","b"]) and dict ({"k":"a"})
• add_edge([a, b], c) fan-in form
• Multi-graph composition (builder.add_node("section", section_builder.compile()))
• LangGraph builtin routers (tools_condition, with hooks for adding more)
• Literal[END, ...] sentinel exit recognition (cycle severity downgrade Critical → Warning)
• Generic-exception fallback to AST when modules side-effect at import (OpenAIError, missing API keys, etc)

Running the same scan on your fork:

shingan analyze --format langgraph --input path/to/graph.py --output markdown

examples/real/ ships three samples written against google.golang.org/adk v1.1.0. Shingan detects the following findings on each:

Run them:

shingan analyze --format adk-go --input examples/real/infinite_loop.go --output markdown
# exit code 2 (Critical)

shingan analyze --format adk-go --input examples/real/unreachable.go --output markdown
# exit code 1 (Warning)

shingan analyze --format adk-go --input examples/real/missing_handler.go --output markdown
# exit code 2 (Critical: loop_guard + Warning: error_handler_checker)

Notes on official ADK-Go SDK coverage:

• Supports the loopagent.New(loopagent.Config{AgentConfig: agent.Config{SubAgents: ...}}) shape (v1.1.0)
• Detects LlmAgent / SequentialAgent / LoopAgent New() constructor patterns via AST
• Resolves tool nodes registered through functiontool.New(Config{Name: "..."}, handler) by following Config.Name and ident references
• Uses a go/types second pass to read functiontool.New[TArgs, TResults](...) generic arguments and infer Tool category from the TArgs struct fields (v0.2.0+, via ParseFile). This is how missing_handler.go's browser_search tool is correctly detected.
• error_handler_checker also fires when an LLM node carries a Tool edge but has no conditional branch (LLM→Tool pattern in ADK-Go)
• ADK-Go SDK v1.1.0 requires go 1.25.0+; reflected in go.mod's minimum version

# E2E auto-verification under the demo build tag
go test -tags=demo -v -run TestDemo_ .

The six v0.9 parsers are PoC-level: each handles idiomatic workflows of its framework. Coverage limits (dynamic graphs, closure branch conditions, split-builder chains, annotation-only return types) are documented per format.

Through v1.0 we commit to no breaking changes in the following public surfaces. The version line below each item is the floor — breaking changes will not happen earlier than the listed major bump.

• Rule names + IDs (cycle_detection, pii_leak_scanner, …) — stable through v1.0. Rules may be added; existing IDs will not be renamed or repurposed.
• .shingan.yaml policy schema — semver-pinned. Additive keys only through v1.0.
• SARIF output structure — conforms to SARIF 2.1.0; shingan-specific extensions live in properties and are append-only through v1.0.
• CLI flags (shingan analyze --format / --input / --output / --min-confidence / --baseline / --since) — stable through v1.0. New flags will be added; existing flags will not change semantics.
• Exit codes (0 = clean, 1 = Warning, 2 = Critical) — stable through v2.0.

Plugin SDK (when it ships in v0.9+) is gated behind an experimental: prefix until v1.0 and explicitly not covered by this commitment.

Static analysis is only useful if developers can trust the output. Shingan tracks Critical false positives as a load-bearing quality metric — we have ended every release sweep at 0 Critical FP since v0.7 (see docs/benchmarks.md for the per-release breakdown).

If you hit a false positive:

1. Open an Issue using the false-positive template — paste the repo URL or minimal repro, the shingan analyze output, and why you believe it's wrong.
2. Critical FP: triaged within 24h on weekdays (best-effort), fix + regression fixture land in the next release with a dogfood-driven CHANGELOG entry.
3. Warning / Info FP: same template, triaged within 1 week.
4. The fix is always a parser/shim precision improvement or a confidence-rule tweak — never silently muting the finding, never moving it to a deny-list.

Every dogfood-driven FP fix shipped since v0.5 is listed in docs/benchmarks.md § Dogfood-driven shim improvements. v0.8.7 alone closed two FPs surfaced by 1.7K-star and ~300-star LangGraph/CrewAI projects.

• v0.1〜v0.5 (Apr 2026): JSON / ADK-Go / Samurai parsers, Confidence × Severity 2-axis, SARIF / GitHub Action, 9 rules ✓
• v0.6 (May 2026): ESLint-style visitor + 3-tier split (ADR-006/007), shingan-lsp, shingan-mcp, LangGraph parser, 20 rules, shingan-lint npm distribution, tag→release→npm-publish automation ✓
• v0.7 (May 2026): n8n parser (pure Go, JSON DSL), bilingual EN/JA docs ✓
• v0.8 (May 2026): CrewAI parser (Python shim, reuses LangGraph PythonWorker), 6 frameworks total ✓
• v0.9+: Mastra parser (TypeScript bridge), 30+ rules, Plugin SDK preview, official site + demo video
• v1.0: 5+ frameworks × 25+ rules, Plugin SDK GA, Marketplace listing

go test ./...
go vet ./...
go build -o shingan ./cmd/shingan
make lint        # check-confidence-reason (go/analysis) + go vet

When adding a new rule, see docs/rule-authoring.md.

• Architecture
• Rule authoring guide (internal)
• Framework parsers: LangGraph · CrewAI · n8n
• Case studies (real OSS dogfood): crewAI-examples · n8n community workflows · gpt-researcher — index
• LSP server (shingan-lsp) — VS Code / Neovim / Helix / Zed setup
• MCP server (shingan-mcp) — Claude Desktop / Cursor / LangGraph Studio setup
• SARIF output + GitHub Code Scanning integration
• diff mode + baseline (--since / --baseline)
• Confidence scoring
• cycle_detection technical note
• All ADRs (001〜013)

Contributors implementing new builtin rules should start with docs/rule-authoring.md. It covers the Local / Path / Global three-tier templates (ADR-007), ConfidenceReason selection guide (ADR-008), the check-confidence-reason go/analysis linter, TDD patterns, and design notes for every existing rule. External rule authors who want to ship rules from their own repo (no fork required) should read docs/plugin-sdk.md — the public plugin.Register API shipped in v0.9 with an experimental: prefix requirement; the stability promise on the ABI lands at v1.0 (ADR-010 originally deferred all external exposure to v1.0; the v0.9 implementation supersedes that with the prefix-gated early-access path).

MIT