{"id":51181527,"url":"https://github.com/perseus-computing-llc/blast-radius-agent","last_synced_at":"2026-06-27T07:03:23.694Z","repository":{"id":364189027,"uuid":"1266818650","full_name":"Perseus-Computing-LLC/blast-radius-agent","owner":"Perseus-Computing-LLC","description":"Blast Radius Analyzer: trace cross-file dependencies with GitLab Orbit before you break things. GitLab Transcend Showcase 2026.","archived":false,"fork":false,"pushed_at":"2026-06-15T23:25:43.000Z","size":3258,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T06:26:18.401Z","etag":null,"topics":["blast-radius","dependency-graph","devtools","gitlab","hackathon","orbit","static-analysis"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Perseus-Computing-LLC.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-12T01:30:18.000Z","updated_at":"2026-06-17T05:08:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Perseus-Computing-LLC/blast-radius-agent","commit_stats":null,"previous_names":["tcconnally/blast-radius-agent","perseus-computing-llc/blast-radius-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Perseus-Computing-LLC/blast-radius-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fblast-radius-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fblast-radius-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fblast-radius-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fblast-radius-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Perseus-Computing-LLC","download_url":"https://codeload.github.com/Perseus-Computing-LLC/blast-radius-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Perseus-Computing-LLC%2Fblast-radius-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34844350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blast-radius","dependency-graph","devtools","gitlab","hackathon","orbit","static-analysis"],"created_at":"2026-06-27T07:03:22.776Z","updated_at":"2026-06-27T07:03:23.677Z","avatar_url":"https://github.com/Perseus-Computing-LLC.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blast Radius Analyzer\n\n[![CI](https://github.com/Perseus-Computing-LLC/blast-radius-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/Perseus-Computing-LLC/blast-radius-agent/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n**Trace cross-file dependencies before you break things.**\n\n### Links\n\n- **Demo video:** https://youtube.com/watch?v=3tibXa-1udE\n- **GitLab AI Catalog agent:** https://gitlab.com/gitlab-ai-hackathon/transcend/39104977/-/automate/agents/1010753/\n- **GitLab project:** https://gitlab.com/gitlab-ai-hackathon/transcend/39104977\n\nEvery developer has shipped a change that broke something downstream — a function signature change that killed an import three projects away, a moved constant that crashed a service you forgot depended on it. CI caught it hours later.\n\nBlast Radius Analyzer fixes this. It's a GitLab Duo custom agent powered by **GitLab Orbit's knowledge graph** that maps every dependency chain before you change code.\n\nMention `@blast-radius` with a file path in any issue or MR comment, and the agent traverses Orbit's dependency graph to show you:\n\n- **Direct impact** — every file that imports your changed code\n- **Transitive impact** — every file that depends on those dependents\n- **Project impact** — which projects are in the blast radius\n- **Risk score** — Low/Medium/High/Critical\n\n## How It Runs\n\nBlast Radius Analyzer has two run modes, and both ship in this repo:\n\n- **Demo / evaluation mode (default, no Orbit needed):** the engine runs against\n  an in-memory graph fixture (`tests/fixtures/sample_graph.json`). This is what\n  the test suite and the demo path exercise, so reviewers can clone and run the\n  full analysis offline with zero external services. The demo video uses a\n  terminal *simulation* (`demo/demo_terminal.html`) for a clean recording — it\n  is clearly labeled as such.\n- **Live mode:** the same engine shells out to `orbit sql` against an\n  Orbit-indexed repository (`blast_radius/orbit_client.py` → `OrbitCLIClient`).\n  Point it at a real Orbit graph and it traverses production dependency data.\n\nThe traversal, cycle handling, and risk scoring are identical in both modes —\nonly the graph source changes. Offline-first is a deliberate choice so the\nproject is fully evaluable without provisioning Orbit.\n\n## Demo\n\n```\nDeveloper: @blast-radius src/auth/tokens.py -- checkToken function\n\n@blast-radius:\n  DIRECT IMPACT (3 files):\n  - src/api/middleware.ts:47 — imports checkToken\n  - src/graphql/resolvers.ts:112 — calls checkToken via auth middleware\n  - src/webhooks/stripe.ts:89 — validates webhook tokens\n\n  TRANSITIVE IMPACT (12 files):\n  - src/api/routes/*.ts — all routes use middleware\n  - src/graphql/schema/*.ts — schema files import resolvers\n  - 3 downstream microservices import the webhook handler\n\n  PROJECT IMPACT: core-api, billing-service, notifications-service\n  RISK SCORE: HIGH — 15 dependents across 3 projects\n\n  Recommended: notify @backend-team before landing this change.\n```\n\n## How It Works\n\nBlast Radius Analyzer is a **custom agent** on the GitLab Duo Agent Platform. It uses GitLab Orbit's knowledge graph to traverse code dependencies:\n\n1. Developer mentions `@blast-radius \u003cfile-path\u003e` in a GitLab issue or MR\n2. Agent queries Orbit's `query_graph` to find all `gl_definition` nodes for the target file\n3. Traverses `gl_reference` edges backwards to find all callers and importers\n4. Recursively traverses to find transitive dependents\n5. Assembles a risk report and posts it as a comment\n\n## Tech Stack\n\n- **GitLab Duo Agent Platform** — custom agent hosting and invocation\n- **GitLab Orbit** — knowledge graph of the codebase (definitions, references, relationships)\n- **Agent Skills** — reusable skill files following the [Agent Skills spec](https://agentskills.io/specification)\n- **Orbit CLI** — local fallback using `orbit sql` for projects without Orbit Remote\n\n## Quick Start\n\n### Prerequisites\n\n- GitLab account with access to a group that has Orbit enabled (or Orbit CLI installed locally)\n- A project with the Blast Radius Analyzer agent enabled\n\n### Setup\n\n1. **Enable the agent** in your GitLab project: Project → AI → Agents → Enable \"Blast Radius Analyzer\"\n2. **Use in any issue or MR**: Comment `@blast-radius src/components/Auth.tsx`\n3. **Read the report**: Agent posts a dependency analysis as a comment\n\n### Run Locally with Orbit CLI\n\nThe repo ships a real local engine (`blast_radius/`) that wraps the Orbit CLI\nand implements cycle-safe, depth-limited traversal with deterministic risk\nscoring. It has zero third-party runtime dependencies.\n\n```bash\n# 1. Install the local engine\npip install -e .\n\n# 2. Install the Orbit CLI from a pinned release (do NOT pipe curl to bash from\n#    a mutable branch). Use the official package or a versioned release asset:\n#    https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/releases\n#    e.g. download the release for your platform, verify its checksum, then:\n#    chmod +x orbit \u0026\u0026 sudo mv orbit /usr/local/bin/\n# Install Orbit CLI (v1.x)\ncurl -fsSL \"https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/v1.0.0/install.sh\" | bash\n\n# 3. Index your project\norbit index /path/to/your/project\n\n# 4. Analyze blast radius\nblast-radius src/auth/tokens.py --function checkToken\n#   or, fully offline against a graph fixture (no Orbit needed):\nblast-radius src/auth/tokens.py --graph tests/fixtures/sample_graph.json --json\n# Analyze blast radius\n./bin/blast-radius-local.sh src/auth/tokens.py 3\n\n# Or query manually\norbit sql \"SELECT t2.name FROM gl_definition t1 JOIN gl_reference ON t1.id = gl_reference.target_id JOIN gl_definition t2 ON gl_reference.source_id = t2.id WHERE t1.path LIKE '%auth.py'\"\n```\n\nConfiguration is read from `.env` (see `.env.example`): Orbit mode, CLI path,\nmax traversal depth, risk thresholds, and exclude patterns.\n\n## Repository Structure\n\n```\nblast-radius-agent/\n├── README.md                    # This file\n├── AGENTS.md                    # Context for AI agents working on this project\n├── agent.yml                    # Deployable GitLab Duo agent manifest\n├── pyproject.toml               # Package metadata + `blast-radius` entrypoint\n├── blast_radius/                # Local engine (Orbit CLI wrapper, traversal, risk)\n│   ├── cli.py                   # `blast-radius` / `python -m blast_radius`\n│   ├── engine.py                # Cycle-safe, depth-limited traversal\n│   ├── orbit_client.py          # Orbit CLI + in-memory fixture clients\n│   ├── risk.py                  # Deterministic risk classification\n│   └── config.py                # .env-driven configuration\n├── skills/\n│   └── blast-radius/\n│       └── SKILL.md             # Reusable blast-radius agent skill\n├── docs/\n│   ├── ARCHITECTURE.md          # Architecture diagrams and flow\n│   ├── ORBIT_CONTRACT.md        # Orbit/Duo tool contract (SQL vs Cypher modes)\n│   └── SUBMISSION.md            # Devpost submission content\n├── scripts/\n│   └── validate_skill.py        # CI validation for skill/manifest/fixture\n├── tests/                       # pytest suite + graph fixture\n├── demo/\n│   ├── demo_script.md           # 3-minute video script\n│   └── demo_terminal.html       # Terminal SIMULATION for demo video\n└── assets/\n    └── thumbnail.png            # Architecture diagram thumbnail\n```\n\n\n\n## Future: GitHub + Local Support\n\nBlast Radius currently requires GitLab Orbit for code graph data. Tree-sitter support\nis planned (see [#45](https://github.com/tcconnally/blast-radius-agent/issues/45))\nto enable analysis on any codebase without GitLab:\n\n- Walk local file tree with tree-sitter\n- Extract symbol definitions and references\n- Build in-memory graph matching the Orbit contract\n- Works on GitHub, Bitbucket, and local-only repos\n\n### Docker\n\n```bash\ndocker build -t blast-radius .\ndocker run blast-radius src/myfile.py --function main\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\nBuilt for the **GitLab Transcend Hackathon** — Showcase Track.  \nDeadline: June 24, 2026 @ 2pm EDT.  \nDevpost: [gitlab-transcend.devpost.com](https://gitlab-transcend.devpost.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperseus-computing-llc%2Fblast-radius-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperseus-computing-llc%2Fblast-radius-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperseus-computing-llc%2Fblast-radius-agent/lists"}