
A zero-daemon, fail-closed deterministic governance harness for AI coding agents with AST
A zero-daemon, fail-closed deterministic governance harness for AI coding agents with AST perception, atomic patching, and empirical benchmarks.
·
Asha verifies AI-generated code changes before you accept them.
Asha sits between an agent and your branch. It freezes the set of files a task may touch, runs the work in its own Git worktree, runs your checks on both the untouched baseline and the result, and records whether the evidence supports accepting the change. When the evidence is missing or inconclusive it refuses instead of reporting success.
Animated overview. Open the interactive demo for chapter
controls, play/pause and a light/dark toggle — standalone HTML, no build step:
open docs/demo.html (macOS), xdg-open docs/demo.html (Linux),
start docs\demo.html (Windows). No hosted demo URL: GitHub Pages is not
enabled for this repository.
Asha is a governance and execution engine for AI-assisted software development. It coordinates workers, controls the changes they declare, verifies their results and seals auditable evidence before integration.
The pieces, kept deliberately separate:
| Layer | Responsibility | Where it lives |
|---|---|---|
| Orchestration and governance | scope, worktree isolation, check matrix, baseline comparison, acceptance, evidence | Asha (asha/) |
| Agent execution and model interaction | running the prompt, calling the model, editing files | Hermes or another supported runner (spec cmd / agent) |
| Reasoning and code generation | producing the patch | the model behind that runner |
| Project environments | tests, lint, type checks | the target repository and its interpreter |
| Acceptance and evidence | PASS/FAIL, seal, ship authorization | Asha, deterministically |
Asha needs no API key for its own job: the model lives behind the runner, and the gates are plain Python.
| Failure | What Asha records |
|---|---|
| Unauthorized file changes | INVALID_EVIDENCE / scope_violation:<path> — any path outside declared_scope |
| Changed paths the caller did not account for | unaccounted_paths + SCOPE_INCOMPLETE (exit 2) |
| No-op worker claiming success | FAILED / output_contract_not_satisfied:* — the declared output contract is read from the tree before sealing |
| Regressions hidden by pre-existing failures | baseline vs. candidate failure identities: NO_FAILURES, PRE_EXISTING_ONLY, NEW_FAILURES, UNKNOWN |
| Unparseable baseline (collection error, crash, timeout) | NOT_COMPARED / UNKNOWN with comparison_inconclusive:baseline_failures_unparsed — never treated as an empty failure set |
| Wrong Python environment | interpreter resolution plus a fail-closed environment-gap diagnosis |
| Missing or inconclusive verification | a skipped required check is never a pass; no_verification_ran is reported |
| Repository-agnostic check matrix blocking a project | a trusted verification profile (0.7.4) declaring REQUIRED vs NOT_CONFIGURED |
| Untrusted verification configuration | profiles are operator-owned, repository-bound, digest-snapshotted, and fail closed |
| Evidence you cannot check later | SHA-256 evidence seal plus offline replay |
asha --exec "cmd" (in-place, governed) and
asha PATH (zero-config status + tip seal).asha run --spec spec.json with
deps, one worktree per worker, topological scheduling
(asha/governance/dag.py).reads, writes,
declared_scope).--apply is given.cmd, or agent + task for a
delegated runner.asha/adapters/ (native, CI, agent).asha/verification_env.py, asha/governance/env_resolver.py).writes, output_kind: changes),
required artifacts (required_artifacts, output_kind: artifact) and
explicit legitimate no-change outcomes (no_change_reason,
output_kind: no_change).docs/WORKER-SKILL-POLICY.md).ASHA_VERIFICATION_PROFILE, docs/verification-profiles.md).NOT_CONFIGURED checks: the latter is recorded with
provenance and never counted as PASS.--acceptance CMD must demonstrably pass; supplied
but not executed, zero tests collected and skip/deselect-only runs fail.asha/evidence.py) and offline replay
(asha/replay.py).--apply runs the integration
gate (asha/integrator.py) and the ship gate
(asha/governance/ship_gate.py). A sealed worker PASS is not ship
authorization.asha-mcp, stdio JSON-RPC 2024-11-05) exposing 14 tools, and
a CLI with a stable JSON contract (schema_version: 1).ASHA_TELEMETRY=1) and a
read-only loopback dashboard (asha dashboard, docs/OBSERVABILITY.md).asha_review* MCP
tools, docs/LADDER.md).--context FILE:SYMBOL and
asha_get_surgical_context (asha/ast_indexer.py, asha/codegraph.py,
asha/context_slicer.py).Task (spec.json, or one governed command)
-> Asha orchestrator / DAG coordinator
-> worker: Hermes, another runner, or a plain command
-> isolated Git worktree (target branch untouched)
-> output contract + declared_scope validation
-> project verification (check matrix or verification profile)
-> baseline vs. candidate failure comparison
-> acceptance validation (when --acceptance is given)
-> SHA-256 evidence seal
-> integration / ship decision (--apply, ship gate)Two distinctions the engine never blurs:
authorized_to_ship: false; the ship gate re-runs the matrix against
the merged tree.UNKNOWN is not SAFE. An inconclusive comparison blocks authorization;
it neither asserts nor rules out a regression.Worktree isolation is path isolation, not a security sandbox.
Requires Python 3.11+ and git. The runtime is stdlib-only — no dependencies.
# from the release wheel (the supported install)
curl -LO https://github.com/xenups/Asha/releases/download/v0.7.4/asha-0.7.4-py3-none-any.whl
python -m pip install asha-0.7.4-py3-none-any.whl
# or from a clone
git clone https://github.com/xenups/Asha.git
cd Asha
python -m pip install -e .Both register the asha and asha-mcp console scripts. Do not run
pip install asha — the PyPI project of that name is unrelated to this one.
Optional extras, only when you use those features:
pip install "asha[code-search]" # tree-sitter / ast-grep AST tooling
pip install "asha[memory]" # mem0 + chroma memory backend
pip install "asha[test]" # pytest, ruff, mypy, mypy-baselineMinimal spec: one worker, one declared write, its own worktree.
{
"workers": [
{
"id": "docs",
"deps": [],
"reads": ["calc.py"],
"writes": ["NOTES.md"],
"declared_scope": ["NOTES.md"],
"cmd": ["python", "-c", "open('NOTES.md','w').write('# notes\\n')"],
"timeout": 120
}
]
}asha --root /path/to/repo run --spec spec.json # audit-only: target untouched
asha --root /path/to/repo run --spec spec.json --apply # apply through the integration gateThe repository must provide the checks to the interpreter Asha resolves
(pytest here); when no check can run the worker is INVALID_EVIDENCE with
reason: no_verification_ran — never a pass.
A successful worker — DONE means own checks passed, the diff stayed inside
declared_scope, the output contract was satisfied, the baseline comparison
ran and found no new failures, and the evidence document was sealed. Output
below is from a fixture repository whose pytest suite passes (abbreviated):
{
"status": "ok",
"completed": ["docs"],
"states": {
"docs": {
"state": "DONE",
"validation_status": "PASS",
"verification_status": "VERIFIED_NO_REGRESSION",
"verdict": "NO_FAILURES",
"baseline_failures": [],
"current_failures": [],
"delta_failures": [],
"comparison": {"performed": true, "comparable": true,
"reason": "COMPARED", "verdict": "NO_FAILURES"},
"output_contract": {"kind": "changes", "declared_writes": ["NOTES.md"],
"writes_observed": ["NOTES.md"], "satisfied": true}
}
},
"evidence": {"docs": ".../orchestrator/task/docs.json"}
}Exit code 0; the target branch is unchanged by an audit-only run.
A repository whose checks cannot produce a parseable baseline (no tests collected, a collection error) is not a pass:
state: FAILED verification_status: COMPARISON_INCONCLUSIVE verdict: UNKNOWNA no-op worker is refused, not excused:
FAILED / output_contract_not_satisfied:no_change_in_declared_writes (no seal)Agents instead of commands: replace cmd with "agent": "<name>" and
"task": "<prompt>". The same spec runs over MCP as asha_run_spec
(simulation unless apply=true).
Inspect evidence: the payload's evidence map points at each worker's
evidence document; asha/replay.py re-hashes it and re-checks byte integrity
instead of trusting the document's own claims.
Exit codes: 0 validation completed / no changes / evaluation-only,
1 validation failed, 2 operational or engine error, 130 interrupted.
--json writes exactly one JSON document to stdout; diagnostics go to stderr.
CLI — flags may appear in any order, and a positional PATH binds the
repository root:
asha PATH # zero-config status + tip seal
asha --verify [PATH] [--base R] [--acceptance CMD]
asha --stack B1 B2 [B3 ...] [--base R] # ordered branch stack, zero worktrees
asha --context FILE:SYMBOL [FILE:SYMBOL ...]
asha --exec CMD... [--base R] [--json] # atomic in-place governed command
asha [--root P] [--paths F ...] [--json] [--no-execute] [--acceptance CMD]
asha status [PATH] [--root P] [--json] # read-only tip facts
asha run --spec FILE [--apply] [--keep-worktrees] [--preserve-on-failure]
asha dashboard [--root P] [--host H] [--port N]MCP server: asha-mcp, or python -m asha.mcp_server (stdio JSON-RPC
2024-11-05, same handlers as the CLI). Registered tools — 14:
| Tool | Kind | Purpose | Required args | Side effects |
|---|---|---|---|---|
asha | execution | single entry point with deterministic routing: cmd > branches > target > validation > bare root | one of cmd, branches, target, validation, root | runs the routed governed operation; returns its payload |
asha_status | read-only | HEAD, porcelain status, worktrees, control-lock state | root | none |
asha_plan_dag | planning | static pre-flight DAG over import edges; never executes | root, workers | none |
asha_run_spec | execution | run a run-spec through the governed engine | spec_path or spec_content | creates worktrees, writes evidence; applies only with apply=true |
asha_dispatch_task | execution | one governed worker through the full pipeline | root, plus prompt or cmd | creates a worktree, runs checks, writes evidence |
asha_verify_tip | verification | in-place, fail-closed verification of the working-tree tip | root | runs checks in place; writes a seal artifact |
asha_verify_stack | verification | verify an ordered branch stack against a base ref, zero worktrees | root, branches, base_ref | runs checks per branch; writes seals |
asha_get_surgical_context | read-only | AST/CodeGraph context for one symbol in one file | repo_path, target_file (or targets) | builds or refreshes the index cache |
asha_review | review | start a Ladder review over a committed range; returns the Code Review packet | root, base, head | persists a review run |
asha_review_context | read-only | bounded chunk of the pinned review target (diff or file) | review_run_id | none |
asha_review_submit_stage | review | submit one stage you produced; validates order, schema, paths | review_run_id, stage, findings, verdict | persists the stage |
asha_review_next_stage | read-only | packet for the next mandatory stage (CODE → SENIOR → SEMANTIC) | review_run_id | none |
asha_review_finalize | verification | deterministic evidence validation plus the canonical ship gate over the submitted stages | review_run_id | persists the delivery decision |
asha_review_status | read-only | read a persisted review by id, including after a restart | review_run_id | none |
Client setup is a standard stdio connection (command: asha-mcp, or
command: python with args: ["-m", "asha.mcp_server"]) for Hermes,
Antigravity, Claude Desktop, Cursor and Windsurf.
| Setting | How | Notes |
|---|---|---|
| Worker policy | ASHA_WORKER_POLICY, or policy fields in the spec | docs/WORKER-SKILL-POLICY.md |
| Skill preload | policy skill resolved from skills/<name>/SKILL.md | fails closed when the Skill is missing; opt out for non-coding work |
| Verification profiles | ASHA_VERIFICATION_PROFILE=/path/profile.json | operator-owned, repository-bound by git remote, digest-snapshotted; never selectable by a task field |
| Python environment | resolved per service and repository; Windows .venv/Scripts and POSIX .venv/bin | see docs/ENVIRONMENT-DIAGNOSIS.md when a failure may be environmental |
| Delegated runner | spec agent + task, or a shipped adapter | the model and its credentials belong to the runner, not to Asha |
| Telemetry and dashboard | ASHA_TELEMETRY=1, then asha dashboard | off by default; loopback only; never evidence |
| Semantic reviewer (optional) | ASHA_SEMANTIC_REVIEW=1 plus ASHA_LLM_* | needs your own API key; disabled unless enabled |
Secrets are read from the environment only; no example in this repository carries a literal credential.
UNKNOWN is not SAFE: an inconclusive comparison blocks authorization
without ruling a regression in or out.no_verification_ran,
EXECUTION_FAILED) rather than passing silently.EXECUTION_FAILED, not as a governance verdict.MIT — see LICENSE. Copyright (c) 2026 Asha contributors.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add asha -- python -m asha.mcp_server{
"mcpServers": {
"asha": {
"args": [
"-m",
"asha.mcp_server"
],
"command": "python"
}
}
}code --add-mcp '{"name":"asha","args":["-m","asha.mcp_server"],"command":"python"}'[mcp_servers.asha]
command = "python"
args = ["-m", "asha.mcp_server"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/asha to learn what the "Asha" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
pip install "asha[code-search]"
pip install "asha[memory]"
pip install "asha[test]"This server runs locally, so we can't read its tool list over the web yet.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/asha)Nothing comparable is listed yet.
v0.7.4v0.7.4 — trusted verification profilesRelease notesv0.7.3v0.7.3 — output contract (no-op runs cannot be DONE)Release notesv0.7.2v0.7.2 — the scoped check path records its environmentRelease notesv0.7.1v0.7.1 — environment diagnosis and a lock guard for governed runsRelease notesv0.7.0v0.7.0 — audited acceptance and a default coding Skill for workersRelease notesv0.6.0v0.6.0 — Task Lifecycle Correlation, Execution Identity & Reproducible JournalsRelease notesv0.5.0v0.5.0 — Governed Comparison Contract, Acceptance Gate & Scope AccountingRelease notesv0.4.2v0.4.2 — Scope Deletion Resilience, AST Syntax Tolerance & In-Place Stack VerificationRelease notesv0.4.1v0.4.1 — order-free CLI & snapshot-safe inner loopRelease notesv0.4.0v0.4.0 — Unified Zero-Friction Entrypoint (one command, one tool)Release notesv0.3.0v0.3.0 — Stack-Native Execution, Auto-Derived Scope & Batch ContextRelease notesv0.2.0v0.2.0 — Real-World Hardening, In-Place Stack Verification & 900-Test BaselineRelease notesv1.0.0Asha-Harness v1.0.0 — Deterministic Governance for AI AgentsRelease notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "asha" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.