https://github.com/sahajamoth/apex
APEX — Autonomous Path EXploration. Drives any repository toward 100% branch coverage.
https://github.com/sahajamoth/apex
agentic-coding ai-agent ai-coding ai-developer-tools ai-testing autonomous-testing code-coverage concolic-execution fuzzing generative-ai llm python rust sast security static-analysis symbolic-execution test-automation testing vibe-coding
Last synced: 4 days ago
JSON representation
APEX — Autonomous Path EXploration. Drives any repository toward 100% branch coverage.
- Host: GitHub
- URL: https://github.com/sahajamoth/apex
- Owner: sahajamoth
- License: mit
- Created: 2026-03-12T13:39:48.000Z (9 days ago)
- Default Branch: main
- Last Pushed: 2026-03-15T23:07:40.000Z (6 days ago)
- Last Synced: 2026-03-16T09:46:36.404Z (6 days ago)
- Topics: agentic-coding, ai-agent, ai-coding, ai-developer-tools, ai-testing, autonomous-testing, code-coverage, concolic-execution, fuzzing, generative-ai, llm, python, rust, sast, security, static-analysis, symbolic-execution, test-automation, testing, vibe-coding
- Language: Rust
- Size: 2.75 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# APEX — Autonomous Path EXploration
[](https://github.com/sahajamoth/apex/actions/workflows/ci.yml)
[](https://github.com/sahajamoth/apex/releases/latest)
[](LICENSE)
**Stop guessing what your tests miss.** APEX finds dead code, flaky tests,
security gaps, and untested branches — then writes the tests to fix them.
---
## What APEX finds in real projects
```
$ apex run --target ./your-project --lang python
╭──────────────────────────────────────────────────╮
│ APEX — Autonomous Path EXploration │
│ Target: ./your-project (Python, 847 branches) │
╰──────────────────────────────────────────────────╯
Round 1/5 ─────────────────────────────────────────
Coverage: 62% → 71% (+9%)
+142 branches covered | 203 remaining | 8 tests written
```
```
Round 5/5 ─────────────────────────────────────────
Coverage: 71% → 94% (+23%)
Final: 798/847 branches covered
Tests written: 31 new tests across 6 files
```
Then ask what it learned:
```
$ /apex-intel
┌─ Test Optimization ──────────────────────────────┐
│ 312 tests → 94 minimal set (3.3× speedup) │
│ 218 tests are redundant — same branch coverage │
└──────────────────────────────────────────────────┘
┌─ Dead Code ──────────────────────────────────────┐
│ 23 branches in 4 files — never executed by any │
│ test or production path │
│ │
│ src/billing.py:89 unreachable after refactor │
│ src/export.py:34 legacy XML path, 0 callers │
│ src/api.py:201 dead error handler │
└──────────────────────────────────────────────────┘
┌─ Flaky Tests ────────────────────────────────────┐
│ 2 tests show nondeterministic branch paths │
│ │
│ test_concurrent_upload — race in file locking │
│ test_session_timeout — depends on wall clock │
└──────────────────────────────────────────────────┘
┌─ Security ───────────────────────────────────────┐
│ src/auth.py:67 — auth bypass: no token check │
│ on admin endpoint (reachable from test_api) │
│ │
│ src/config.py:12 — hardcoded secret: │
│ AWS_KEY = "AKIA..." (not from env) │
└──────────────────────────────────────────────────┘
┌─ Hot Paths ──────────────────────────────────────┐
│ src/auth.py:45 — 12.3% of all branch hits │
│ src/db.py:112 — 8.7% of all branch hits │
│ These functions need the most test coverage. │
└──────────────────────────────────────────────────┘
Deploy Score: 87/100 — GO
```
---
## Installation
**Standalone installer** (recommended — macOS and Linux):
```bash
curl -sSL https://raw.githubusercontent.com/sahajamoth/apex/main/install.sh | sh
```
**Homebrew:**
```bash
brew install sahajamoth/tap/apex
```
**npm:**
```bash
npx @apex-coverage/cli run --target . --lang python
```
**pip:**
```bash
pipx install apex-coverage
```
**Nix:**
```bash
nix run github:sahajamoth/apex
```
**Cargo** (from source):
```bash
cargo install --git https://github.com/sahajamoth/apex
```
Build from source with optional features
```bash
# Prerequisites
rustup component add llvm-tools-preview
cargo install cargo-llvm-cov
# Clone and build
git clone https://github.com/sahajamoth/apex.git && cd apex
cargo build --release
# With optional heavy features (Z3, LibAFL, PyO3)
cargo build --release --features "apex-symbolic/z3-solver,apex-fuzz/libafl-backend"
```
---
## Claude Code-first
APEX is built for Claude Code. The primary interface is slash commands and
auto-triggered agents — not a CLI you have to learn.
### Slash Commands
| Command | What it does |
|---------|-------------|
| `/apex` | **Dashboard** — deploy score, key findings, recommended next actions |
| `/apex-run` | **Autonomous loop** — measures gaps, writes tests, re-measures, repeats |
| `/apex-index` | Build per-test branch index for intelligence commands |
| `/apex-intel` | Full SDLC intelligence — test quality, risk, dead code, hotpaths, contracts |
| `/apex-deploy` | Deployment readiness — GO / CAUTION / BLOCK with confidence score |
| `/apex-status` | Coverage table for the workspace |
| `/apex-gaps` | Top uncovered regions with explanations and suggested tests |
| `/apex-generate` | Generate tests targeting uncovered branches in a crate |
| `/apex-ci 0.8` | CI gate — fails if below threshold |
### Auto-triggered Agents
These fire automatically when Claude Code detects a matching intent:
| Agent | Trigger examples |
|-------|-----------------|
| **apex-coverage-analyst** | "what's our coverage?", "which parts are uncovered?" |
| **apex-test-writer** | "write tests for X", "improve coverage in Y" |
| **apex-runner** | "run apex against Z", "run apex on itself" |
| **apex-sdlc-analyst** | "what's our deploy score?", "find flaky tests" |
### Strategy Selection
The `/apex-run` loop automatically picks the best strategy per gap:
| Target | Primary | Fallback |
|--------|---------|----------|
| Rust workspace | Source-level tests | fuzz harness |
| Python project | Source-level tests | concolic execution |
| C/Rust binary | fuzz | driller (when fuzz stalls) |
| JavaScript | Source-level tests | — |
---
## Standalone CLI — 20 commands, 6 packs
Core
```bash
apex run --target ./project --lang python # Coverage gap report
apex ratchet --target ./project --min-cov 0.8 # CI gate
apex doctor # Check dependencies
apex audit --target ./project --lang python # Security audit
```
Pack A: Per-Test Branch Index
```bash
apex index --target ./project --lang python --parallel 8
```
Runs each test individually under coverage, builds a map of test→branches.
Stored in `.apex/index.json`. Required before intelligence commands.
Pack B: Test Intelligence
```bash
apex test-optimize --target . # Minimal test subset
apex test-prioritize --target . --changed-files src/auth.py
apex flaky-detect --target . --lang python --runs 5
```
Pack C: Source Intelligence
```bash
apex dead-code --target . # Semantically dead code
apex lint --target . --lang python # Runtime-prioritized lints
apex complexity --target . # Exercised vs static complexity
```
Pack D: Behavioral Analysis & CI/CD
```bash
apex diff --target . --base main # Behavioral diff
apex regression-check --target . --base main # CI gate for behavior changes
apex risk --target . --changed-files src/auth.py
apex hotpaths --target . --top 20
apex contracts --target . # Discover invariants
apex deploy-score --target . # Aggregate confidence 0-100
```
Pack E: Documentation
```bash
apex docs --target . --output docs/behavioral.md
```
Pack F: Security
```bash
apex attack-surface --target . --lang python --entry-pattern test_api
apex verify-boundaries --target . --lang python \
--entry-pattern test_api --auth-checks check_auth --strict
```
---
## Architecture
Rust workspace, 16 crates. Heavy dependencies (Z3, LibAFL, PyO3, Inkwell,
Firecracker) are behind feature flags — not compiled by default.
| Crate | Role |
|-------|------|
| `apex-core` | Shared types, traits, config |
| `apex-coverage` | Coverage oracle, bitmap tracking, continuous branch distance heuristics |
| `apex-instrument` | Multi-language instrumentation (Python, JS, Java, Rust, LLVM, WASM) |
| `apex-lang` | Language-specific test runners |
| `apex-sandbox` | Process / WASM / Firecracker isolation |
| `apex-agent` | AI-driven test generation, priority scheduler, solver cache |
| `apex-synth` | Test synthesis via Tera templates + LLM-guided refinement loop |
| `apex-symbolic` | SMT-LIB2 constraint solving, gradient descent solver (optional Z3) |
| `apex-concolic` | Concolic execution (optional PyO3 tracer) |
| `apex-fuzz` | Coverage-guided fuzzing with MOpt (optional LibAFL) |
| `apex-detect` | Security patterns, hardcoded secrets, CWE-mapped findings |
| `apex-cpg` | Code Property Graph — taint analysis via reaching definitions |
| `apex-index` | Per-test branch indexing, SDLC analysis |
| `apex-rpc` | gRPC distributed coordination |
| `apex-mir` | MIR parsing, control-flow analysis |
| `apex-cli` | CLI binary — 20 subcommands |
### Analysis Mechanisms
APEX integrates fundamental mechanisms from established tools
(see [docs/INSPIRATION.md](docs/INSPIRATION.md) for details):
| Mechanism | From | APEX Crate |
|-----------|------|------------|
| Continuous branch distance (Korel fitness) | EvoMaster | `apex-coverage` |
| Gradient descent constraint solving | Angora | `apex-symbolic` |
| Code Property Graph + taint analysis | Joern | `apex-cpg` |
| LLM-guided test refinement (closed loop) | CoverUp | `apex-synth` |
| Priority-based exploration scheduler | Owi + EvoMaster | `apex-agent` |
| Solver caching with negation inference | Owi | `apex-agent` |
Optional feature flags
| Feature | Crate | Enables |
|---------|-------|---------|
| `llvm-instrument` | apex-instrument | LLVM-based instrumentation via inkwell |
| `wasm-instrument` | apex-instrument | WebAssembly instrumentation |
| `z3-solver` | apex-symbolic | Z3 SMT solver |
| `kani-prover` | apex-symbolic | Kani bounded model checking |
| `pyo3-tracer` | apex-concolic | Python concolic tracer |
| `libafl-backend` | apex-fuzz | LibAFL fuzzer backend |
| `firecracker` | apex-sandbox | Firecracker microVM isolation |
```bash
cargo build --release --features "apex-symbolic/z3-solver,apex-fuzz/libafl-backend"
```
---
## Configuration
```toml
# apex.toml
[coverage]
target = 1.0
min_ratchet = 0.8
[fuzz]
corpus_max = 10000
stall_iterations = 50
[agent]
max_rounds = 3
[sandbox]
process_timeout_ms = 10000
```
## Development
```bash
cargo test --workspace
cargo fmt --check
cargo clippy --workspace -- -D warnings
```
## License
[MIT](LICENSE)