Integrates with OpenAI-compatible chat-completions endpoints to generate bounded unified-diff repair candidates during verification, subject to policy checks and Docker sandbox validation.
Provides Prometheus query adapters for canary SLO monitoring, enabling progressive deployment watchers to detect threshold breaches and request rollback through a configured traffic controller.
Astrix is a local-first DevOps verification engine. It selects tests from source-level dependency impact, enforces AxLang-authored policies, optionally runs bounded LLM-assisted repair in an isolated sandbox, and exposes analysis tools over MCP.
Astrix is under active development. Review policies, deployment integrations, and generated changes before using them in production workflows.
Choose the setup that fits your workflow. The installer and GitHub Action install Astrix; the Action also installs axc to validate Astrixfile.ax.
curl -fsSL https://raw.githubusercontent.com/vivek5200/astrix/main/install.sh | sh -s -- --bin-dir "$HOME/.local/bin"Add $HOME/.local/bin to PATH if it is not already there. The installer downloads the latest published release and verifies its checksum when available. If you want to edit or validate .ax files directly, install the AxLang compiler too:
go install github.com/vivek5200/axlang/cmd/axc@latestFrom the root of a supported project, run:
astrix init && astrix verifyastrix init creates Astrixfile.ax and will not overwrite an existing file. astrix verify runs the detected project test command; set ASTRIX_TEST_COMMAND when your project needs a custom command. The Astrix CLI can create and use its config without the standalone axc binary; install axc separately to run compiler commands such as axc check Astrixfile.ax.
Use a published Astrix release tag that contains action.yml in your workflow. Pinning the tag makes the CI version explicit:
name: Astrix
on: [push, pull_request]
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: vivek5200/astrix@<release-tag>
with:
version: <release-tag>
command: verifyThe Action installs Astrix and axc, checks Astrixfile.ax, then runs the selected command. The version input pins the installed CLI to the same release as the Action. To initialize a repository, set command: init; run verification in a later workflow run after the generated config is committed. Replace both <release-tag> values with a published tag that includes the composite action.
go install github.com/vivek5200/astrix/cmd/astrix@latest
go install github.com/vivek5200/axlang/cmd/axc@latest
astrix mcp configastrix mcp config prints copyable MCP setup for Claude Code, Cursor, and VS Code. Keep astrix on the PATH inherited by the MCP client. AxLang's axc is needed to check or format .ax files; the Astrix MCP server itself runs as astrix mcp serve.
Related MCP server: uacos
astrix CLI: validates Astrixfile.ax, prints symbol graphs or diff blast radiuses, verifies changes, optionally requests a bounded repair, and serves MCP tools.
astrixd daemon: accepts HMAC-signed webhook requests and checks incoming diffs for credentials and policy violations.
AxLang: the companion compiler for workspace, stage, policy, repair, and deployment declarations. The standalone compiler lives at github.com/vivek5200/axlang.
pkg/astgraph normalizes source definitions and references into a shared graph of symbol nodes, definition edges, and reference edges. Go files use the standard-library Go parser; JavaScript/JSX, TypeScript/TSX, and Python use Tree-sitter adapters. Other UTF-8 text files receive a conservative file-level node, so projects using other languages remain visible to astrix graph and changed files are not silently dropped. Add a Tree-sitter adapter to get symbol-level dependency traversal for another language. Binary assets and generated/dependency/cache directories are skipped.
astrix graph .
astrix graph . --symbol ParseConfig
astrix graph . --diff changes.patchThe JSON graph output includes source locations and file hashes. The --diff form emits changed symbols, the transitive impact set, and selected tests. For languages without an AST adapter, blast radius is file-level and cannot infer callers or select language-specific tests reliably.
pkg/cache derives stable SHA-256 keys from symbol subgraphs and edges and stores verification outcomes beneath .astrix/cache. pkg/runner tracks bounded per-test outcome history in SQLite and computes a rolling failure fraction for quarantine decisions. The cache is local to the repository unless an external cache layer is added by the caller.
Astrixfile.ax policies compile through AxLang to Rego v1 and are evaluated by the embedded OPA engine against an ActionIntent. Guardrails can deny an action or require approval. Diff glob rules operate on the modified-file list; secret scanning runs at ingress and blocks findings before policy evaluation.
When a policy requires approval, the gate returns a requires_approval decision and keeps the action blocked until an approved intent is supplied. The current CLI stops on that decision; Astrix does not yet provide operator notifications or an approval inbox. Integrators should surface the request through their CI or deployment platform and require authenticated human approval before resuming.
astrix verify --fix runs verification, sanitizes nondeterministic log details, constructs a repair prompt with impact context, and requests a unified diff from an OpenAI-compatible endpoint. The patcher bounds attempts to three, rejects forbidden test changes, applies policy before acceptance, and verifies candidate changes in a disposable Docker sandbox with networking disabled. Keep credentials in environment variables or a local ignored .env file.
astrix verify detects common project test runners (Go, npm, pytest, Cargo, Maven/Gradle, .NET, Composer, Bundler, and Make). For another build system or a monorepo with a nonstandard command, set ASTRIX_TEST_COMMAND to a JSON argument array, such as ASTRIX_TEST_COMMAND='["./scripts/check.sh","--ci"]' astrix verify. This runs the command directly without a shell. For astrix verify --fix, set ASTRIX_SANDBOX_IMAGE to an image with the required toolchain; the repair sandbox has no network access and mounts existing node_modules and vendor trees read-only. Other offline dependencies must be available through the selected image or project setup. Common-language AST support and test-command detection are separate capabilities: unknown languages still receive file-level graph coverage, while test execution uses the project's detected or configured command.
astrix mcp serve runs JSON-RPC over stdio and exposes astrix_get_blast_radius, astrix_evaluate_policy, and astrix_run_impacted_tests so compatible clients can inspect impact, evaluate an intent, and run selected tests.
pkg/canary maps a validated AxLang deploy declaration to progressive traffic steps, polling intervals, and SLO thresholds. It provides Prometheus query and HTTP traffic-controller adapters. On a breached SLO, the watcher requests rollback through the configured controller. Integrators supply endpoints and deployment credentials.
Go 1.26 or newer for this module.
Docker for isolated repair verification.
An OpenAI-compatible model endpoint for LLM-assisted repair.
go install github.com/vivek5200/astrix/cmd/astrix@latest
go install github.com/vivek5200/astrix/cmd/astrixd@latestInstall axc and axls from the companion AxLang project.
Create a local .env in the repository root for model-assisted repair:
ASTRIX_LLM_BASE_URL=http://localhost:8000/v1
ASTRIX_LLM_API_KEY=replace-with-your-local-key
ASTRIX_LLM_MODEL=your-model-nameASTRIX_LLM_ENDPOINT can provide a full chat-completions URL. Process environment settings take precedence over .env. Never commit real credentials.
The daemon accepts ASTRIX_WEBHOOK_SECRET and ASTRIXD_ADDR; it serves /healthz and an HMAC-SHA256 authenticated /webhook. It does not terminate TLS, so deploy it behind a TLS-terminating reverse proxy on a trusted network.
astrix check [Astrixfile.ax]
astrix graph [path] [--symbol name]
astrix graph [path] --diff changes.patch
astrix verify
astrix verify --fix
astrix mcp servego test -race ./...
go vet ./...
go build ./cmd/astrix ./cmd/astrixdThe live Docker/LLM scenario is skipped if its endpoint credentials or Docker daemon are unavailable. It can be run explicitly with:
go test -v ./e2e -run '^TestLiveDockerAndLLM_ClosedLoopSelfHealing$' -count=1Set ASTRIX_RUN_LIVE_E2E=1 to opt into that test; ordinary go test ./... runs the deterministic suite and skips external LLM calls.
The dual-repository workspace includes a self-hosted validation workflow and a root Makefile; see the workspace overview for commands.
See ARCHITECTURE.md for graph, policy, repair, and runtime subsystem details.
Apache License 2.0. See LICENSE.
Evaluate a proposed ActionIntent against the Astrixfile.ax policies in the opened repository and return allowed, denied, and requires_approval booleans with an optional reason. Use this before carrying out a proposed action; it evaluates policy but does not execute the action. For changed-file impact use astrix_get_blast_radius, and for selected test execution use astrix_run_impacted_tests. The required intent object contains actor.type, target.env, modified_files, and diff.modifies_tests (the string "true" or "false"); set approved=true only when approval has already been recorded.
| Name | Required | Description | Default |
|---|---|---|---|
| intent | Yes |
| Name | Required | Description |
|---|---|---|
| denied | Yes | Whether an explicit policy rule denies the action. |
| reason | No | Explanation of the policy decision, when available. |
| allowed | Yes | Whether policy permits the proposed action, including any approval requirement. |
| requires_approval | Yes | Whether policy requires approval before the action may proceed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds real value: it clarifies the tool evaluates but never executes, and that approved=true must only be set when approval is already recorded. It does not cover failure modes or error behavior, so it stops short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences that front-load the action and outputs, then prerequisites, then routing. No filler, though the intent-field enumeration makes the final sentence long and slightly hard to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A nested, single-parameter mutation-lookalike gate tool with an output schema present; the description supplies the intent shape, the approval precondition, and the non-execution guarantee. Return values are already in the output schema, so the remaining gaps are minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Top-level schema description coverage is 0%, and the single nested intent object is the whole payload, so the description carries the burden well: it enumerates actor.type, target.env, modified_files, and diff.modifies_tests, and flags the counterintuitive string "true"/"false" enum that is easy to get wrong. Nested field descriptions in the schema duplicate some of this, keeping it from a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (evaluate) plus resource (a proposed ActionIntent against Astrixfile.ax policies), and it names the exact outputs (allowed, denied, requires_approval with optional reason). It is cleanly differentiated from the two siblings by scoping itself to policy evaluation rather than impact analysis or test execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to call it ("Use this before carrying out a proposed action") and what it is not ("does not execute the action"). It also routes to the right alternatives by name: astrix_get_blast_radius for changed-file impact and astrix_run_impacted_tests for selected test execution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze the current staged and unstaged Git diff against HEAD in the opened repository and return changed symbols, their reverse-dependency impact, selected tests, and changed-file ranges. Use this before astrix_run_impacted_tests to inspect what the diff affects; this tool only reads repository state and does not run tests. It accepts no arguments.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| impact | Yes | |
| changes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds real value by stating the analysis scope (staged + unstaged diff vs HEAD) and reinforcing that no tests are executed, which is the key behavioral distinction from the sibling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: what it returns, when to use it, and the no-argument constraint. Nothing is redundant and the scope statement is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-arg read-only analysis tool with an output schema present, everything an agent needs is here: the input diff basis, the returned artifacts, and the routing relationship to the test-running sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero-parameter tool, which is baseline 4. The description confirms 'It accepts no arguments', aligning with the empty schema and preventing an agent from trying to pass a repo path or diff range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('Analyze the current staged and unstaged Git diff against HEAD') and enumerates the outputs (changed symbols, reverse-dependency impact, selected tests, changed-file ranges). This clearly distinguishes it from astrix_run_impacted_tests, which runs tests rather than inspecting the diff.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly gives ordering guidance: 'Use this before astrix_run_impacted_tests to inspect what the diff affects', and rules out the adjacent behavior with 'does not run tests'. Missing only an explicit statement of when not to use it (e.g., clean working tree or committed-range analysis).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recompute the blast radius from the current staged and unstaged Git diff against HEAD in the opened repository, then execute the selected Go test packages (or the full Go suite if no test symbols map to packages). Use this to verify changed code after reviewing impact with astrix_get_blast_radius; it recomputes from the workspace and does not reuse a prior tool call's state. Test code runs locally with the current process permissions and may access the network or create or modify files. Returns selected test symbols on success; test failures are returned as tool errors. It accepts no arguments.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| tests | Yes | Test symbols selected and executed from the current diff's blast radius. |
| passed | Yes | True when all selected test packages pass. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations flag destructive/openWorld/non-idempotent, and the description goes beyond them by disclosing that test code runs locally with the current process permissions and may access the network or create/modify files. It also states success returns selected test symbols and that test failures surface as tool errors, which is not derivable from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action, followed by routing guidance, then safety and return semantics. No filler and nothing a caller must infer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the recompute-from-workspace behavior, the fallback to the full Go suite when no symbols map, the zero-argument contract, permission/network/file side effects, and error semantics. With an output schema present, return-value detail is already handled, so nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, which sets the baseline at 4. The description reinforces this with 'It accepts no arguments,' matching the empty schema, but there is no additional parameter-level meaning to convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb chain ('recompute the blast radius ... then execute the selected Go test packages') with a named resource and diff scope (staged/unstaged against HEAD). It also names the sibling it complements, so an agent can separate it from astrix_get_blast_radius without reading either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it ('verify changed code after reviewing impact with astrix_get_blast_radius') and adds a critical exclusion: it recomputes from the workspace and does not reuse a prior tool call's state. That tells the agent this is not a cheap follow-up to a previous blast-radius call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.3astrix_evaluate_policy4 fields changedInput schema / additionalPropertiesPrevious value: -trueNew value: +falseInput schema / properties / intentAdded value: +{
+ "additionalProperties": false,
+ "properties": {
+ "actor": {
+ "additionalProperties": false,
+ "properties": {
+ "id": {
+ "description": "Optional actor identifier.",
+ "type": "string"
+ },
+ "type": {
+ "description": "Actor category evaluated by policy, for example autonomous_llm or human.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ "approved": {
+ "description": "Whether the required human approval has already been recorded.",
+ "type": "boolean"
+ },
+ "diff": {
+ "additionalProperties": false,
+ "properties": {
+ "modifies_tests": {
+ "description": "Whether the proposed diff modifies test files, represented as the string true or false.",
+ "enum": [
+ "true",
+ "false"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "modifies_tests"
+ ],
+ "type": "object"
+ },
+ "modified_files": {
+ "description": "Repository-relative paths the proposed action would modify.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "target": {
+ "additionalProperties": false,
+ "properties": {
+ "env": {
+ "description": "Target environment, for example staging or production.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "env"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "actor",
+ "target",
+ "modified_files",
+ "diff"
+ ],
+ "type": "object"
+}Input schema / requiredAdded value: +[
+ "intent"
+]Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": false,
+ "properties": {
+ "allowed": {
+ "description": "Whether policy permits the proposed action, including any approval requirement.",
+ "type": "boolean"
+ },
+ "denied": {
+ "description": "Whether an explicit policy rule denies the action.",
+ "type": "boolean"
+ },
+ "reason": {
+ "description": "Explanation of the policy decision, when available.",
+ "type": "string"
+ },
+ "requires_approval": {
+ "description": "Whether policy requires approval before the action may proceed.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "allowed",
+ "denied",
+ "requires_approval"
+ ],
+ "type": "object"
+}astrix_get_blast_radius2 fields changedInput schema / additionalPropertiesPrevious value: -trueNew value: +falseOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": false,
+ "properties": {
+ "changes": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "deleted": {
+ "description": "Whether this diff deletes the file.",
+ "type": "boolean"
+ },
+ "new_file": {
+ "description": "Whether this diff adds the file.",
+ "type": "boolean"
+ },
+ "old_path": {
+ "description": "Previous path for a rename, when present.",
+ "type": "string"
+ },
+ "path": {
+ "description": "Changed repository-relative path.",
+ "type": "string"
+ },
+ "ranges": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "end": {
+ "description": "Last changed line in the new file.",
+ "type": "integer"
+ },
+ "start": {
+ "description": "First changed line in the new file.",
+ "type": "integer"
+ }
+ },
+ "required": [
+ "start",
+ "end"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "path",
+ "ranges"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "impact": {
+ "additionalProperties": false,
+ "properties": {
+ "changed_symbols": {
+ "description": "Symbols whose source lines overlap the current diff.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "impacted_symbols": {
+ "description": "Symbols in the reverse-reference closure of changed symbols.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "tests": {
+ "description": "Test symbols selected by the blast-radius analysis.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "required": [
+ "impact",
+ "changes"
+ ],
+ "type": "object"
+}astrix_run_impacted_tests2 fields changedInput schema / additionalPropertiesPrevious value: -trueNew value: +falseOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": false,
+ "properties": {
+ "passed": {
+ "description": "True when all selected test packages pass.",
+ "type": "boolean"
+ },
+ "tests": {
+ "description": "Test symbols selected and executed from the current diff's blast radius.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "tests",
+ "passed"
+ ],
+ "type": "object"
+}v0.1.0astrix_evaluate_policyastrix_get_blast_radiusastrix_run_impacted_testsScored across 3 tools
The three tools have distinct roles: policy evaluation, diff impact inspection, and test execution. However, blast radius and impacted tests both analyze the same Git diff, and the test runner recomputes blast radius internally, creating some conceptual overlap that descriptions mostly resolve.
All tool names use the same astrix_ prefix followed by a clear verb_noun pattern: evaluate_policy, get_blast_radius, run_impacted_tests. The convention is predictable and readable.
Three tools are well-scoped for a focused policy-and-impact-analysis workflow. Each tool has a clear, non-redundant purpose in the lifecycle from policy check to impact inspection to test execution.
The surface covers the core loop of evaluating a proposed action, inspecting blast radius, and running impacted tests. A minor gap exists around recording or retrieving approval status, which the policy tool references but no tool provides.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
