stability-analysis-agent 1.2.7

Stability Analysis Agent: AI-assisted crash log analysis toolchain (CLI, daemon, analyzers, agent)

Stability Analysis Agent

An AI Agent for App Stability — from crash log to root cause in one step
_{Crash · ANR · OOM · Freeze analysis | addr2line / atos symbolizer | LangGraph AI Agent | RAG knowledge base}

English | 简体中文

---

Stability Analysis Agent is an open-source AI Agent framework for app stability analysis, designed to evolve across crash, ANR (Application Not Responding), OOM (Out of Memory), and freeze / watchdog scenarios. The first production-ready scenario today is crash analysis; ANR, freeze, and memory-focused workflows are under active evolution. Feed it a stability log, and it will parse, symbolize, extract code, reason about the root cause, and generate fix suggestions — automatically. Supports iOS, Android, macOS, Linux, and Windows with built-in addr2line / atos integration, LangGraph multi-turn reasoning, and a RAG knowledge base (ChromaDB).

Why not just paste the log into an AI coding tool?

General-purpose AI coding tools (Cursor, Copilot, Claude Code, etc.) can read a crash log, but they hit hard limits on stability analysis:

• Raw addresses are meaningless — AI tools cannot run addr2line / atos; they see 0x1a2b3c instead of MyClass::process() at main.cpp:42.
• Stability logs are noisy — hundreds of system frames drown the real signal; without structured parsing, the LLM wastes tokens on irrelevant context.
• No domain memory — every conversation starts from scratch; learned patterns (crash signatures, ANR deadlock traces, OOM heuristics) are lost.

This Agent solves all three:

	AI Coding Tool	Stability Analysis Agent
Address symbolization	Cannot run native tools	Built-in addr2line / atos integration
Log parsing	Sees raw text, high noise	Structured parser extracts signal, threads, key frames; classifies crash / ANR / OOM / freeze
Knowledge accumulation	Stateless, starts from zero	RAG: rule table + vector DB, patterns improve over time
Workflow	Single-prompt, one-shot	Multi-step Agent with conditional multi-turn reasoning
Extensibility	Prompt-only	Tool + Workflow + Skill system, config-driven

Agent Engine

Three execution modes to fit different needs:

Mode	Engine	Best for
Direct	One-shot prompt assembly	Fast, simple, no framework dependency
LangChain	LangChain Agent	Flexible tool calling with chain-of-thought
LangGraph	LangGraph state machine	Multi-turn reasoning, the Agent can request more context and re-invoke tools

Select via --engine direct|langchain|langgraph. All modes share the same tool chain and RAG knowledge base.

No LLM API key required to run the core toolchain (parsing + symbolization + code extraction). Plug in any OpenAI-compatible model (GPT, DeepSeek, ERNIE, GLM, etc.) when you're ready for AI analysis.

Key Features

Feature	Description
Multi-Step AI Agent	LangGraph / LangChain / Direct — multi-turn reasoning with conditional branching
Address Symbolization	Resolves raw addresses to function names & line numbers via addr2line / atos
Structured Log Parsing	Auto-detects iOS / Android / macOS / Linux / Windows; classifies crash, ANR, OOM, freeze; extracts signal, threads, key frames
Source Code Context	Extracts code snippets around crash points
RAG Knowledge Base	Rule table (fast path) + vector retrieval (ChromaDB) with feedback loop
Tool + Workflow System	Pluggable architecture — register custom tools and workflows via config or decorators
Skill System	Discover / install / lint / init / run Claude-style SKILL.md skills, or bridge them into the existing Tool/Workflow runtime
Closed-Loop Skill Templates	Two built-in --preset scaffolds (automation-testing, cicd-pipeline) for the “verify-then-package” repair loop
External Agent Skill Pack	Bundled stability-analysis-agent-skill/ — teach Claude Code, Cursor, and other agents how to install and run sa-agent
Multiple Interfaces	CLI, HTTP Daemon (streaming / SSE), Python API

Architecture

                  ┌──────────┐   ┌──────────┐   ┌──────────┐
                  │   CLI    │   │  Daemon  │   │  Python  │
                  │          │   │  (HTTP)  │   │   API    │
                  └────┬─────┘   └────┬─────┘   └────┬─────┘
                       │              │              │
                       └──────────────┼──────────────┘
                                      │
                            ┌─────────▼─────────┐
                            │ Tool + Workflow +  │
                            │     Skill         │
                            └─────────┬─────────┘
                                      │
          ┌───────────────────────────┼───────────────────────────┐
          │                           │                           │
          ▼                           ▼                           ▼
   ┌────────────┐            ┌────────────┐            ┌────────────┐
   │  Crash Log │            │  Address   │            │    Code    │
   │   Parser   │            │ Symbolizer │            │  Provider  │
   └────────────┘            └────────────┘            └────────────┘
                                      │
                            ┌─────────▼─────────┐
                            │    AI Agent       │
                            │  ┌─────────────┐  │
                            │  │  LangGraph  │  │
                            │  │  State      │  │
                            │  │  Machine    │  │
                            │  └──────┬──────┘  │
                            │         │         │
                            │    ┌────▼────┐    │
                            │    │   RAG   │    │
                            │    │ Rules + │    │
                            │    │ Vectors │    │
                            │    └────┬────┘    │
                            │         │         │
                            │    ┌────▼────┐    │
                            │    │   LLM   │    │
                            │    └─────────┘    │
                            └───────────────────┘

Agent Pipeline:

Crash Log → Parse → Symbolize → Extract Code
                                      ↓
                              RAG (rules + vectors)
                                      ↓
                                LLM Reasoning ←──→ Request More Context (multi-turn)
                                      ↓
                                 Fix Report

For detailed architecture diagrams, see docs/architecture.

Quick Start

Prerequisites

• Binary usage: no Python runtime required
• Python version: minimum 3.9; recommended 3.10–3.12 (primary CI coverage)
  • Core only (parse + symbolize + LLM): 3.9+ is generally fine
  • With [rag] (torch / transformers): prefer 3.10–3.12; 3.9 may hit ML stack issues
  • On macOS, prefer Homebrew / pyenv Python over python.org installers without CA setup (SSL)
• (Optional) atos (macOS, built-in) or addr2line (Linux, via binutils) for symbolization

Install and Launch (Recommended)

Option A — pip (venv or system environment)

# Install (for Mainland China, add -i https://pypi.tuna.tsinghua.edu.cn/simple)
pip install stability-analysis-agent

# With vector DB / similar-case RAG (recommended for full experience)
pip install "stability-analysis-agent[rag]"

# Open the interactive wizard
sa-agent

Option B — pipx (isolated CLI, no global site-packages pollution)

# Install pipx first: https://pipx.pypa.io/
pipx install stability-analysis-agent
# Or with RAG (large download, slower first install)
pipx install "stability-analysis-agent[rag]"

sa-agent --help

Option C — prebuilt binary: see “Use Prebuilt CLI Binary” below.

See docs/cli/INSTALL_TROUBLESHOOTING.md for Python versions, SSL, pipx, transformers / nn errors, etc.

The UX is intentionally Claude CLI-like: arrow-key menus, grouped "More options", clear back paths, and concise confirmations.
In most cases, you can finish configuration + analysis + AI fix flow directly in the terminal.

Demo: Interactive AI Fix (Crash)

Use the bundled demo case to experience the end-to-end AI path:

git clone https://github.com/baidu-maps/stability-analysis-agent.git
cd stability-analysis-agent
sa-agent

In the wizard, choose 快速开始分析（推荐）, then enter:

crash_log  -> examples/crash_cases/demo_basic/logs/mac/NullPtr_SIGSEGV_2026-04-08_10-43-08.crash
library_dir -> examples/crash_cases/demo_basic/lib/mac
code_root  -> examples/crash_cases/demo_basic/code_dir

The CLI prints an execution plan and runs automatically. In AI mode, it performs parse + symbolize + code-context extraction + LLM reasoning, and can apply fix suggestions with backup.

To analyze your own case, run sa-agent and input your own paths using the same flow.

Use with External AI Agents (Claude / Cursor)

If you already use Claude Code, Cursor, or similar AI coding tools, install the bundled skill pack so the agent knows how to call this toolchain (symbolization, structured reports, --scope, etc.) — instead of guessing commands or pasting raw logs only.

This is not the same as sa-agent skill install (runtime extensions for sa-agent). The pack lives at stability-analysis-agent-skill/ and is copied into your external agent's skill directory.

Step 1 — install the Python package (provides sa-agent):

pip install stability-analysis-agent
# or: pipx install stability-analysis-agent

Step 2 — install the skill pack into your agent:

git clone https://github.com/baidu-maps/stability-analysis-agent.git
cp -R stability-analysis-agent/stability-analysis-agent-skill ~/.claude/skills/stability-analysis-agent

For Cursor (project-level example):

mkdir -p .cursor/skills
cp -R stability-analysis-agent/stability-analysis-agent-skill .cursor/skills/stability-analysis-agent

After that, ask your agent to analyze a crash log with Stability Analysis Agent — it should propose sa-agent commands, pick the right --scope, and read cli_reports/<timestamp>/ outputs.

Resource	Description
SKILL.md	Main entry for external agents
examples.md	Copy-paste command examples
reference.md	Flags, reports, config paths
docs/skills/README.md	sa-agent Skill System (runtime extensions)
docs/skills/CLOSE_LOOP_SKILL_TEMPLATES.md	automation-testing / cicd-pipeline closed-loop templates

No LLM key? The skill documents --scope gen_prompt_only — full parse + symbolize + code context + prompt file, without calling an LLM.

Skill System (sa-agent Runtime Extensions)

The skill_system/ package and sa-agent skill … subcommands add a pluggable extension layer inside sa-agent (distinct from the external-agent skill pack above). A Skill is a directory containing a Claude-style SKILL.md plus an optional machine-readable skill.json; installed skills can be discovered at startup, rendered as prompt snippets, or bridged into the existing Tool / Workflow runtime.

CLI Subcommands

# Discover, list, show
sa-agent skill list [--skill-dir PATH]… [--json]
sa-agent skill show <name> [--json]

# Validate
sa-agent skill lint <path-to-skill-dir> [--json]

# Install / uninstall (directories or .zip archives)
sa-agent skill install <source-dir-or.zip> [--target-root PATH] [--overwrite]
sa-agent skill uninstall <name> [--target-root PATH]

# Scaffold a new skill (claude-style prompt or workflow/tool/plugin)
sa-agent skill init <name> <target-dir> [--type prompt|workflow|tool|plugin] \
                   [--preset automation-testing|cicd-pipeline]

# Execute: render prompt, or invoke exported workflow/tool
sa-agent skill run <name> [args…] [--input path/to/input.json] [--json]

Closed-Loop Skill Presets

Two --preset scaffolds cover the “fix → verify → package” loop:

Preset	Purpose	When to use
automation-testing	Run automated tests / smoke / regression checks on a repaired artifact	Right after fix candidates are produced
cicd-pipeline	Package, build, publish or hand off the repaired artifact	Right after a fix has been verified

sa-agent skill init automation-testing-skill ./automation-testing-skill --preset automation-testing
sa-agent skill init cicd-pipeline-skill     ./cicd-pipeline-skill     --preset cicd-pipeline

sa-agent skill install ./automation-testing-skill
sa-agent skill install ./cicd-pipeline-skill

In the interactive sa-agent wizard, the menu now exposes a “修复闭环 Skill 模板 / Closed-Loop Skill Templates” entry that shows the recommended init/install commands and the current install status (sa-agent skill show …) for each preset — a quick way to bootstrap project-specific verification or CI/CD skills. See docs/skills/CLOSE_LOOP_SKILL_TEMPLATES.md.

The closed-loop presets are intentionally lightweight starter scaffolds: they ship only SKILL.md + skill.json. Extend them with project-specific scripts, reference docs, or exports before relying on them in production.

Discovery and Install Paths

• Default install root: ~/.config/stability-analysis-agent/skills (override with --skill-home or STABILITY_AGENT_SKILL_HOME).
• On startup, sa-agent also discovers skills in:
  • ~/.claude/skills
  • ./.claude/skills (current working directory)
  • <repo>/.claude/skills
  • any extra path passed via --skill-dir or STABILITY_AGENT_SKILL_DIRS (PATH-list separator).
• Supported packaging formats: a skill directory or a .zip archive whose top level is a skill directory.

Bridging Skills into Tool / Workflow

skill.json declares an entrypoint plus an exports array:

entrypoint	Runtime behavior
prompt	Render SKILL.md, substitute $ARGUMENTS / $SKILL_NAME / $SKILL_DIR, return a prompt string
workflow:<name>	Call the workflow registered via exports.kind = workflow
tool:<name>	Call the tool registered via exports.kind = tool

A workflow/tool skill can register its exports back into the tool_system registry so the existing executor (ConfigDrivenExecutor / LangGraph routes) can pick them up:

{
  "id": "crash-analysis-skill",
  "command_name": "crash-analysis",
  "type": "workflow",
  "entrypoint": "workflow:crash_analysis",
  "exports": [
    {
      "kind": "workflow",
      "ref": "my_package.my_skill:CrashAnalysisWorkflow",
      "name": "crash_analysis",
      "priority": "CUSTOM",
      "force_override": false,
      "enabled": true
    }
  ]
}

For a complete end-to-end example (install → lint → run), see docs/skills/README.md and docs/skills/SKILL_TEMPLATE.md.

Other Ways (Advanced)

Programmatic API (embedding / enterprise wrappers)

Since v1.2.4, the wheel includes a stable Python surface in cli/api.py, for example execute_analysis, build_parser, collect_interactive_run_state, interactive_state_to_argv, run_from_interactive_state, and run_cli_main. Use it to drive the same pipeline from custom menus or automation without subprocess. See CHANGELOG.md.

For skill system integrators, the public surface is exposed via skill_system/:

from skill_system import (
    SkillManager, SkillRuntime,
    load_skill_bundle, parse_skill_directory,
    available_skill_presets, write_skill_scaffold,
)

manager = SkillManager()        # uses the standard discovery roots
runtime = SkillRuntime(manager)

# Scaffold + write a starter skill
write_skill_scaffold("./my-skill", "my-skill", preset="automation-testing")

# Render prompt-style skill
prompt = runtime.render("my-skill", arguments="issue-123 json").prompt

# Execute workflow/tool skill against a JSON payload
result = runtime.execute("crash-analysis-skill", input_payload={
    "crash_log": "...", "library_dir": "./lib", "code_root": "./code"
})

Use Prebuilt CLI Binary (No Python Required)

Download the latest binary from GitHub Releases. Zip/folder names are versioned; use names from the release you downloaded.

unzip StabilityAnalyzer-v1.2.4-mac-arm64.zip
cd output/cli_release/stability_analyzer_cli/v1.2.4-mac-arm64
./StabilityAnalyzer

Developer Setup (from Source)

git clone https://github.com/baidu-maps/stability-analysis-agent.git
cd stability-analysis-agent
pip install -e .
sa-agent

pip install -e . is intended for development workflows and also exposes the local sa-agent command.

CLI Options

Flag	Required	Description
--crash-log	Yes	Path to the crash log file (any extension; content-based parsing — see Crash log formats)
--library-dir	Yes*	Directory with libraries (.dylib/.so) and debug symbols (.dSYM)
--code-root	No	Source code root for extracting code context
--scope <value>	No	Agent run scope (default full). One of full / gen_prompt_only / parse_stack_only / parse_log_only. See below.
--daemon <url>	No	Delegate to a running daemon instance

* Not required when using --scope parse_log_only.

--scope values

Value	Behavior
full (default)	Parse + symbolize + extract code context + LLM analysis (with optional auto-fix).
gen_prompt_only	Run the full toolchain but skip the LLM call; emit a reusable prompt file.
parse_stack_only	Only parse + symbolize. --code-root not needed.
parse_log_only	Only parse the crash log. Neither --library-dir nor --code-root is needed.

Supported crash log files and platforms

File extensions: not restricted — .crash, .txt, .log, .json, or no suffix all work if the content matches a known format. You can also pass - for stdin. RTF exports are converted to plain text automatically.

Text reports (examples): Apple .crash, iOS freeze/Mach exports, Android logcat/tombstone, Harmony Stacktrace: / Tid: dumps, native #NN pc stacks.

JSON exports:

Platform / shape	log_format (in 01 report)
Harmony crash platform (crashDiagnosis: / crashDiagnsis: + JSON, incl. #NN pc in body.stacks)	harmony_crash_diagnosis_json
Sentry event JSON	sentry_event_json
Firebase Crashlytics event JSON	firebase_crashlytics_json
Bugsnag event JSON	bugsnag_event_json
Other dashboards (Bugly-like, custom APM) with frames / stack_frames arrays	generic_json_stack_export

Full matrix, parser priority, and how to add adapters: docs/tools/CRASH_LOG_FORMATS.md · 中文版

Daemon Mode

The daemon provides streaming output (SSE), process reuse (no cold start), and task cancellation — ideal for IDE integration and high-frequency analysis:

# Start the daemon
sa-agent --daemon-server --host 127.0.0.1 --port 8765

# Analyze via daemon
sa-agent --daemon http://127.0.0.1:8765 \
  --crash-log <crash-log> --library-dir <lib-dir> --code-root <code-root>

See Daemon Server Guide for the full HTTP API reference.

Python API

from tool_system import (
    ToolAndWorkflowRegistry, SystemConfig, WorkflowConfig,
    ConfigDrivenExecutor, register_all_tools_and_workflows
)

registry = ToolAndWorkflowRegistry()
register_all_tools_and_workflows(registry)

config = SystemConfig(
    workflows=[WorkflowConfig(name="crash_analysis", enabled=True)]
)
executor = ConfigDrivenExecutor(registry, config, llm_adapter=None)

result = executor.execute_workflow("crash_analysis", {
    "crash_log": open("crash.crash").read(),
    "library_dir": "./lib",
    "code_root": "./code"
})
print(result)

LLM and Tool Configuration

For LLM and add2line setup, use the interactive wizard:

sa-agent

Then enter 设置 -> 配置大模型 / 配置堆栈地址解析工具. Checks and guidance run contextually in flow. For stack symbolization: Auto-detect (recommended) and Manually set absolute path to the symbolizer (executable or directory containing it). When you choose Quick start and the run needs symbolization, the CLI also tries the same silent auto-write as Auto-detect first to avoid repeating setup.

Default local config directory:

~/.config/stability-analysis-agent/

• agent_config.local.json for LLM vendor selection (active_provider key), credentials, and model
• add2line_resolver_config.local.json for symbolizer search paths (tool_paths = directories; optional environment_vars for toolchain roots such as NDK, often filled by auto-detect)

If you prefer manual editing, edit these files directly in that directory.

Optional advanced run modes (via --scope):

• --scope gen_prompt_only (full toolchain, skip LLM, emit prompt file)
• --scope parse_stack_only (parse + symbolize only)
• --scope parse_log_only (parse log only)

Advanced: add2line config override

You can override add2line config file location via environment variable:

export STABILITY_AGENT_ADD2LINE_CONFIG_FILE="/abs/path/add2line_resolver_config.local.json"

Project Structure

stability-analysis-agent/
├── agent/              # AI Agent engine (LangGraph state machine)
├── cli/                # CLI entry point
├── daemon/             # HTTP daemon (streaming, SSE)
├── tools/              # Tool implementations (parser, resolver, code provider)
│   └── configs/        # Configuration templates
├── tool_system/        # Tool + Workflow registration & dispatch framework
├── skill_system/       # Skill discovery, install, runtime bridge (CLI subcommands)
│   ├── cli.py          # `sa-agent skill …` argparse subparser
│   ├── manager.py      # SkillManager: discover / install / lint / register
│   ├── runtime.py      # SkillRuntime: render prompt / execute workflow / execute tool
│   ├── templates.py    # `available_skill_presets()` + scaffold writer
│   ├── models.py       # SkillBundle / SkillExport / SkillRunResult dataclasses
│   └── parser.py       # `SKILL.md` + `skill.json` parser
├── workflows/          # Workflow definitions (crash analysis)
├── rag/                # RAG: rule store + vector index (ChromaDB) + metadata
├── prompts/            # Prompt templates for LLM analysis
├── protocol/           # Unified request/response protocol
├── examples/           # Bundled crash cases
│   └── crash_cases/
│       ├── demo_basic/         # NullPtr, DivZero, Abort, DoubleFree, etc.
│       └── demo_multithread/   # Race condition, deadlock, atomic failure, etc.
├── test/               # Test suite
├── stability-analysis-agent-skill/  # External agent skill pack (Claude / Cursor)
└── docs/               # Documentation

Documentation

Topic	Link
CLI Guide	docs/cli/CLI_GUIDE.md
CLI Commands Reference	docs/cli/CLI_COMMANDS_REFERENCE.md
Daemon Server Guide	docs/cli/DAEMON_SERVER_GUIDE.md
External Agent Skill Pack	stability-analysis-agent-skill/
Skill System (sa-agent runtime)	docs/skills/README.md
Closed-Loop Skill Templates	docs/skills/CLOSE_LOOP_SKILL_TEMPLATES.md
Skill Template Reference	docs/skills/SKILL_TEMPLATE.md
PyPI Release Scripts	docs/scripts/PYPI_RELEASE_SCRIPTS.md
System Architecture	docs/architecture/README.md
Architecture Diagram	docs/architecture/ARCHITECTURE_DIAGRAM.md
Tool System Overview	docs/tools/tool_system/TOOL_SYSTEM_OVERVIEW.md
Tool Extension Guide	docs/tools/tool_system/TOOL_SYSTEM_EXTENSION.md
Workflow System	docs/workflows/WORKFLOWS.md
RAG Vector Database	docs/rag/README.md
Crash Demos	docs/crash_cases/README.md
Crash log formats & platforms	docs/tools/CRASH_LOG_FORMATS.md

Testing

# Regression tests
python3 test/tool_system/test_regression.py

# LLM connection test
python3 test/llm/test_llm_connection.py --provider openai

# Code content provider test
python3 test/agent_py_tool/test_code_content_provider.py

# Vector database test
python3 test/agent_py_tool/test_vector_db.py

# Skill System (parser, install, lint, runtime bridge)
python3 test/skill_system/test_skill_system.py

FAQ

Q: Symbolization failed? Ensure --library-dir contains the binary files (.dylib / .so) along with their debug symbols (.dSYM directories or DWARF info). In interactive mode, use Settings → Configure stack symbolization tools with Auto-detect or Manually set absolute path to the symbolizer (executable or directory). You can also edit ~/.config/stability-analysis-agent/add2line_resolver_config.local.json (see tools/configs/add2line_resolver_config.local.example.json).

Q: LLM call failed? Verify your API key is set correctly. Quick check: python3 test/llm/test_llm_connection.py --provider openai

Q: Code context extraction returns empty? Ensure --code-root points to the source directory that contains the files listed in the symbolized stack trace.

Q: Can I use this without an LLM key? Yes. Use --scope gen_prompt_only to run the full toolchain (parse + symbolize + extract code) without calling the LLM. The structured JSON output is useful on its own for triage and debugging.

Q: How do I use this from Claude Code or Cursor? Install the Python package (pip install stability-analysis-agent), then copy stability-analysis-agent-skill/ into your agent's skill directory (e.g. ~/.claude/skills/stability-analysis-agent). See Use with External AI Agents above.

Q: How do I add my own Skill (custom verify step, custom CI, etc.) inside sa-agent? Use sa-agent skill init <name> ./<dir> --preset automation-testing|cicd-pipeline to scaffold a starter, or sa-agent skill init <name> ./<dir> for a blank prompt/workflow/tool skill. After filling in your logic, install it with sa-agent skill install ./<dir> and verify with sa-agent skill list / sa-agent skill show <name>. For skills that should plug into the executor, declare entrypoint and exports in skill.json — see Skill System above and docs/skills/SKILL_TEMPLATE.md.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a PR.

# All commits require DCO sign-off
git commit -s -m "feat: describe your change"

License

Apache License 2.0

Contact

Channel	Link
GitHub Issues	Report a bug or request a feature
Email	[e-mail]

Maintainer:

Name	GitHub	Email
liuhong	@liuhong996	[e-mail]

---

If this project helps you, please consider giving it a Star!