Mortis Engine
Review local Git changes, verify findings and scan repository security with your saved AI connection. Mortis sends eligible source and diffs to that connection and checks reported evidence against the pinned Git revisions.
Install from this repository
uv tool install --editable .
mortis --help
Requires Python 3.13–3.15 and Git. Development defaults to Python 3.15 through
.python-version; uv can provide the compatible Python interpreter.
To install a built release wheel, use uv tool install /path/to/mortis_engine-0.1.0-py3-none-any.whl.
PyPI publication is pending; the release guide describes the
prepared workflow. Trivy is required for security scans and Docker is optional
for code graph context; neither executable is bundled in the Python package.
Choose what to review
| Command | Source |
|---|---|
mortis review |
Current working tree against HEAD, including staged, unstaged and eligible untracked files |
mortis review --staged |
Git index against HEAD |
mortis review --base main --head feat/update-opentui |
Changes from the common ancestor through the named branch tip |
mortis review --all |
Every eligible tracked file in the current commit |
mortis review --all --head feat/update-opentui |
Every eligible tracked file in that branch's latest local commit |
Use --effort low, --effort medium or --effort high to override the repository setting for one run. Local working-tree and staged reviews use an immutable snapshot and leave your Git index, objects and refs untouched. Working-tree reviews require an initial commit. Ignored untracked files, credentials and excluded files are outside review scope.
Preview the same local planner without an AI connection or saved analysis run:
mortis review --base main --preview
mortis review --all --preview --format json
The preview lists selected and excluded files, exclusion reasons, source/diff bytes,
units and planned batches. --prompt-token-ceiling reproduces a connection's input
bound without loading its credentials. Batch counts exclude provider envelopes,
evidence followups and later workflow stages. See preview details.
New full-tree reviews send source once; historical resumed plans retain their original
representation and task identities. The fixed-input measurement
records the byte and batch reduction.
Use --concurrency 1 through --concurrency 8 to override the repository setting for a review or security scan. Reviews default to two concurrent AI batches; a batch may contain multiple files. Scans default to four concurrent file analyses. The override applies only to that run and leaves mortis.toml unchanged.
Separate Mortis processes sharing the same local state directory also share a ceiling of eight active model requests per connection. This applies across repositories and workflow stages. Profiles using the same destination and credential reference share capacity even with different names or models. Progress shows waiting requests; waiting counts toward the configured deadline. This coordinates local clients, not provider account rate limits or other machines. Different credential references form separate groups, even when they happen to contain the same API key.
Add --progress for a compact live view showing reviewed and failed file counts, active AI requests and elapsed time. Files in active requests appear on separate rows, with up to three names and a count of any others. Mortis sends files in batches; file counts update when a request finishes and its results pass validation. Redirected progress uses plain lines. Every review prints its elapsed time to stderr, including failed or interrupted attempts; resuming measures the current invocation. Progress and timing keep JSON on stdout valid.
The view also shows possible findings as validated analysis results arrive. During assessment it shows assessed/total candidates, unique confirmed findings, rejected and uncertain candidates, failed assessments and duplicate confirmations. Failed assessments count as processed candidates and remain separate from rejected findings. These counts stay visible through summary generation. Scan progress shows Trivy findings separately from AI proposals and confirmations; unobserved findings retained from earlier scans are not counted as current confirmations. Finding text remains in the final report.
Review a branch
From your working branch, run:
mortis review --base main --head HEAD
Mortis uses your only saved profile automatically. With several profiles, select one by name:
mortis review --base main --head HEAD --connection opencode-go --format json
Mortis compares the common ancestor of the two commits with the head commit. Local edits and untracked files are outside this comparison. Branches, tags and commit IDs must be available in the local clone. Use --repo to select another repository. GitHub access and a running Code Mortis instance are unnecessary.
Create an optional mortis.toml on the base branch to configure the review:
[review]
language = "Spanish"
effort = "medium"
review_sensitivity = "balanced"
max_files = 40
concurrency = 2
timeout_seconds = 300
token_budget = 100000
max_output_tokens = 32768
[[review.rules.rules]]
path = "**/*.py"
rule = "Check that exceptions preserve committed data."
merge_system_rule = true
Use mortis config show --base main to inspect the effective settings. The base commit controls the rules, file exclusions, background context and optional model override. A profile supplies the endpoint and credentials. Analysis, candidate assessment, fix verification and summaries each use their configured token budget. Use assessment_token_budget, verification_token_budget, summary_token_budget and summary_timeout_seconds to configure follow-up stages. summary_diagram_enabled enables a structured diagram and ai_fix_prompts_enabled includes repair prompts for open findings. For working-tree, staged and full-tree reviews, Mortis reads settings from the selected committed revision.
CLI flags override the committed TOML settings for one run without changing the file:
mortis review --all --max-output-tokens 0 --token-budget 0 --timeout-seconds 0 --max-files 0
mortis scan --max-output-tokens 32768 --assessment-token-budget 200000
mortis summary --run RUN_ID --max-output-tokens 32768 --summary-token-budget 0
Use 0 for unlimited total token budgets, overall timeouts and maximum files. It is normalized to no limit internally. Concurrency still requires 1–8. Provider request timeouts, transport size limits and provider account/model limits still apply.
max_output_tokens controls each AI response, including reasoning, across analysis and follow-up stages. An explicit value is preserved during recovery. With 0, Mortis omits the output cap for OpenAI Chat Completions and Responses protocols and lets the provider choose its default; this does not guarantee the model's maximum. If a total token budget is finite, Mortis instead bounds output by the remaining budget and serializes these requests so concurrent work cannot reserve the same tokens. A provider may reject a remaining budget above its model's output maximum; set a positive max_output_tokens in that case. Anthropic Messages and Bedrock require an explicit maximum, so those connections need a positive value. Omitting the setting preserves the existing 16,384-token requests and recovery up to 32,768 tokens.
Review flags also include --assessment-token-budget, --verification-token-budget, --summary-token-budget and --summary-timeout-seconds. Scans support the assessment and verification budget flags. Standalone verification uses --verification-token-budget; background generation uses --token-budget. These commands support --max-output-tokens and their corresponding overall timeout flag. --resume restores the saved overrides and rejects new limit flags.
Mortis assesses candidates before reporting confirmed findings and generates a summary of the reviewed changes. The JSON report retains rejected and uncertain candidates. With auto_resolve = true, later reviews of the same scope check earlier open findings against both revisions. A verified fix can update the current local status. Earlier reports remain available by ID.
Default-omitted tests may be read as pinned supporting evidence without becoming review targets. Explicit exclusions and protected paths still apply. Tests are never executed: only their supplied inputs and assertions can support or refute a claim. Assessment can request bounded merge-base evidence to distinguish an existing defect from one introduced or activated by the change. Full-tree reviews continue to evaluate defects present at the selected revision.
For an exact Python line replacement, Mortis checks the proposed source in memory. If a valid original would become syntactically invalid, the confirmed finding remains and its suggestion is withheld. Ambiguous replacements and originally invalid source retain the assessor's decision; this check does not establish runtime correctness. See Python suggestion checks for the exact limits.
Discovery can search a literal symbol in bounded, permitted source at the pinned revision, including unchanged files. Matches are navigation hints, not proof of a caller relationship: Mortis requires a separate source read before accepting a citation. This works without Docker; aliases and dynamic access may be missed. See symbol search limits.
The optional --second-pass experiment searches for additional candidates through the
same analysis budget and normal assessment. It is disabled by default and can also be
configured with [review].second_pass = true; resume retains the saved choice. A failed
second pass preserves validated first-pass results and reports incomplete analysis.
See the experiment and the offline evaluation
for limits and the evidence required before considering default enablement.
The report includes commit IDs, findings, evidence, file and unit coverage, errors and token usage. A file counts as fully reviewed only when all assigned units pass validation. Missing token usage is reported as unknown. JSON on stdout uses mortis.review/v1. Progress goes to stderr. Exit status 0 indicates completed analysis or no eligible changes, 2 indicates partial coverage or a file-limit skip, and 1 indicates failure. Findings are available even in a partial report.
Save and export reports
Use --output once or several times to save a review or security scan. The filename
extension selects Markdown (.md or .markdown) or structured JSON (.json):
mortis review --all --progress --output review.md --output review.json
mortis scan --ref HEAD --progress --output scan.md --output scan.json
The terminal still shows the normal report; --format json continues to control stdout.
Progress and elapsed time stay on stderr. Both files describe the same analysis and
do not require extra AI calls. Partial reports are saved too, with their incomplete
coverage and errors preserved; review and scan exit codes retain their usual meaning.
Markdown includes the summary and any generated groups/diagram, findings and evidence,
supported suggestions or remediation, coverage, errors, model, token usage and duration.
JSON contains the complete versioned result. New review/scan results save
elapsed_seconds, measuring the analysis invocation, including preparation and follow-up
stages but excluding export. For resumed runs it measures that invocation. Older saved
reports remain unchanged and show unavailable timing rather than an estimated duration.
Export an existing saved result without a connection or another analysis:
mortis report --run RUN_ID --output reports/review.md --output reports/review.json
Use --repo when selecting a different local repository. The export uses the original
saved review or scan report; later retries and triage remain available through
mortis findings. Successful export returns exit code 0 even if the saved analysis was
partial; its original status remains in the report.
Output files are private to the current user. Missing parent directories are created when saving. Existing files, symlinks, duplicate destinations and unsupported extensions are rejected, so reports cannot overwrite source or prior output. Choose new filenames when saving another report. A write failure reports the saved run ID so you can export it again without repeating analysis.
When saving inside the repository, add the output directory to .gitignore if you
want future working-tree reviews to exclude those generated reports.
Saved results and follow-up commands
mortis runs
mortis runs RUN_ID
mortis verify --run RUN_ID --ref HEAD
mortis summary --run RUN_ID
mortis background --ref HEAD
mortis runs lists IDs for the current repository. Replace RUN_ID with an ID from that list. Verification checks the earlier finding against current source. Background prints a proposed project description. To use it in reviews, save it under [review].background in the trusted configuration.
Run history, task reservations and retained snapshot objects live under $XDG_STATE_HOME/mortis (default ~/.local/state/mortis). These private files can contain reviewed source. Use mortis review --resume RUN_ID to continue an interrupted review with its pinned revisions and saved connection. Each workflow accepts --resume. Validated task results can be reused. A request interrupted after dispatch retains its reservation with unknown usage.
Resumed reviews and scans keep their saved concurrency override. Omit --concurrency when using --resume; --progress can be enabled when resuming.
Retry a failed assessment
mortis assessments --run RUN_ID
mortis assess --run RUN_ID --candidate CANDIDATE_ID --progress
mortis assess --resume RETRY_RUN_ID --progress
Reviews and security scans save candidate assessment inputs before dispatch. The listing
shows which failed candidates can be retried and explains blocked retries. A targeted
retry assesses only that candidate using its original source, settings and connection.
It saves a separate mortis.assessment/v1 result and prints its run ID, verdict and any
confirmed finding. Analysis, Trivy and summary generation are not repeated. Repeating a
successful retry returns the saved result.
Retries have their own invocation deadline and assessment budget, with usage recorded
separately and cumulatively across the candidate's attempts. Unknown token consumption
blocks a retry and retains its reservation. Changed connections or missing original
evidence also block dispatch. Older runs without saved assessment inputs remain readable
but cannot be retried through this command. Original reports, coverage and grades stay
available through mortis runs RUN_ID.
A change to finding decisions in the scope blocks a retry whose saved history is stale. If decisions change while a retry runs, its result and usage are saved for inspection, and the result does not update current findings.
Record finding decisions
mortis findings --run RUN_ID
mortis triage --run RUN_ID --finding FINDING_ID --state dismissed --version 0 --reason "Caller already checks this condition"
mortis findings --run RUN_ID --history --format json
mortis findings shows the current findings for that run's scope, including confirmed
assessment retries and local decisions. Review decisions support dismissed and open.
Security decisions support false_positive, accepted_risk and open. Reopen a finding
by selecting open and supplying the current version printed by mortis findings.
Every decision requires a reason. A stale version is rejected so simultaneous commands
cannot overwrite each other's decisions.
Decisions apply to subsequent runs in the same repository and scope. They are saved in
an audit trail alongside the original reports, and require no AI connection. Evidence
outcomes remain visible separately from user decisions. Accepted risks still count toward
security ratings; false positives do not count in future ratings. Triage does not claim
that a fix was verified or a reported secret was rotated. All four follow-up commands
support --repo and --format json.
Scan security
mortis scan --ref HEAD
mortis scan --ref main --format json
mortis scan --concurrency 8 --effort high --progress
--progress shows the same compact live view as reviews, including snapshot preparation, Trivy checks, active AI file analyses, assessment and verification. File counts include only validated analysis results. Every scan prints elapsed time to stderr, with or without progress, including failed or interrupted attempts. JSON reports remain on stdout.
The scan requires Trivy 0.76.0 on PATH. Trivy refreshes its advisory database, then checks dependencies, configuration and secrets against an isolated local snapshot. Semantic analysis, candidate assessment and verification use the selected AI profile. Repository source is excluded from the Trivy update request. For a supported npm CVE without an established fixed version, verification can look up the CVE ID in GitHub's public advisory database. A partial scan keeps its coverage and findings and reports an unavailable grade.
An optional [scan] table in mortis.toml accepts model, effort, concurrency, language, exclusions, timeout_seconds, token_budget, max_output_tokens, assessment_token_budget and verification_token_budget. The scan output limit inherits [review].max_output_tokens unless overridden in [scan]. Scan defaults use high effort and four concurrent file requests. mortis config show displays effective review and scan settings. After rotating or revoking a reported secret, pass --acknowledge-rotation FINDING_ID on the next scan of that scope so Mortis can verify removal. Use the ID printed with the original finding.
Optional code graph
mortis graph build
mortis review --base main --graph
Docker builds a separate parser image with the pinned grammars. During review the parser receives bounded file contents at one revision. It runs without network or host mounts. A review records unavailable graph context and can continue using its normal source evidence.
Set extraction limits in the trusted committed configuration:
[review.code_graph_limits]
max_files = 1000
max_file_bytes = 1048576
max_source_bytes = 8388608
For one run, use mortis review --graph --graph-max-files 2000 or the corresponding
--graph-max-file-bytes and --graph-max-source-bytes flags. Individual flags preserve
the other committed limits. mortis config show displays effective values. Defaults are
1,000 files, 1 MiB per file and 8 MiB total; maximum values are 5,000 files, 4 MiB per file
and 32 MiB total. All must be positive integers, and the individual file limit must fit
within the total limit. These bounds cannot be made unlimited. Resume restores saved
limits and rejects new overrides. Persistent graph storage and querying belong to the app.
Connect interactively
mortis connect
In a terminal, mortis connect asks for the connection details you leave out. Flags supply those values directly. For scripts, use --non-interactive with an environment variable for the key.
For OpenCode Go, run:
mortis connect opencode-go --model muse-spark-1.3-contributor
A new profile named after a provider uses that preset’s protocol and URL. With the model supplied, paste your key at the hidden prompt and press Enter. Mortis tests the connection and saves it to your OS credential vault. An existing profile keeps its own provider settings.
Use --advanced to edit protocol, endpoint, options and extra headers interactively. A blank header entry keeps the current headers; {} clears them. The same settings can be supplied directly through flags. Use --api-key-env VARIABLE to read a key from the environment. Enter ? at the model prompt to select from the provider catalog. Bedrock also supports AWS credentials.
Model listing is optional and depends on provider support. For providers without discovery, including Bedrock, enter the model ID directly. The connection test makes two small model requests to verify a tool-call round trip and may consume provider tokens. It saves the profile after the test succeeds. Failures identify the selected profile and never switch providers. A failed edit preserves the previous saved connection.
mortis connect work --test
mortis connect work --list-models
mortis connect --list-providers
mortis config show
mortis config show work
Provider options are stored as JSON within the TOML file to preserve provider-specific values such as null. Profiles are stored in ~/.config/mortis/config.toml, or $XDG_CONFIG_HOME/mortis/config.toml when set. mortis config show displays connection settings and credential references, with vault contents omitted. Running mortis connect work edits that profile. Changing provider, endpoint, protocol or authentication destination requires selecting credentials again.
Connect with environment variables
Set MORTIS_API_KEY securely in your shell or secret manager, then run the following. The saved profile refers to that environment variable, so it must also be set for subsequent tests.
mortis connect work \
--provider openai \
--model YOUR_MODEL \
--api-key-env MORTIS_API_KEY \
--non-interactive
Custom endpoints support an explicit protocol and API URL.
mortis connect local \
--provider custom \
--protocol openai \
--base-url http://localhost:4000/v1 \
--model YOUR_MODEL \
--api-key-env MORTIS_LOCAL_KEY \
--options '{"timeout_sec":120,"prompt_token_ceiling":58888}' \
--non-interactive
For a trusted HTTP or private-network endpoint, set CM_ALLOW_PRIVATE_ENDPOINTS=true, or explicitly allow its hostname with CM_TRUSTED_ENDPOINT_HOSTS=localhost. Explicit hostname trust allows that destination through the endpoint checks. Use a placeholder key for a local provider that does not require authentication. Endpoint policy comes from these environment settings and is not loaded from repository files.
Extra header values can also come from environment variables.
mortis connect work \
--headers-env '{"X-Custom-Header":"MORTIS_CUSTOM_HEADER"}' \
--non-interactive
Use --headers-env '{}' to clear extra headers. A supplied --options object replaces the saved provider options. Otherwise edits retain existing options for the same provider. All four API protocols are supported: openai, openai-responses, anthropic, and anthropic-bedrock. Provider presets are packaged with the CLI.
| Option | Meaning |
|---|---|
timeout_sec |
Provider request timeout, 5–900 seconds |
prompt_token_ceiling |
Conservative input ceiling per request, 4,096–2,000,000 tokens |
retry_codes |
Provider HTTP 4xx codes classified as retryable by the transport |
extra_body |
Additional provider request fields, with input and authentication protections |
auth_header |
Custom authentication header name |
aws_region |
Bedrock region |
aws_profile |
AWS credential profile for Bedrock |
Bedrock can use ambient AWS credentials or an API key supplied through the same environment or vault methods.
mortis connect aws \
--provider bedrock \
--model YOUR_BEDROCK_MODEL_ID \
--ambient-auth \
--options '{"aws_region":"us-east-1","aws_profile":"work"}' \
--non-interactive
Development
Coding-agent guidance and the project Codex roles are documented in AGENTS.md.
GitHub Actions runs the test suite on Python 3.13, 3.14 and 3.15 for pushes to main
(including merges), pull requests targeting main and manual dispatches.
Python 3.15 checks Ruff, builds and checks the wheel/source distribution and
smoke-tests isolated installations. Python 3.13 tests native graph extraction with
the parser's pinned dependencies. Provider, Trivy
and Docker boundaries use mocks in this suite; CI does not make live analysis requests.
uv sync --locked --group dev
uv run --locked pytest -q
uv run --locked ruff check .
uv build
uv run --locked python scripts/check_dist.py
The mortis_engine.cli package contains terminal commands. Python callers can import review_local or review_commits from mortis_engine.review and use mortis_engine.operations.run for verification, summaries, background and scans. These entry points return the same versioned dictionaries as the CLI JSON output.
mortis_engine.operations also exports list_assessments, retry_assessment,
list_findings and triage for the corresponding local follow-up commands.
Read CONTRIBUTING.md before contributing and SECURITY.md to report a vulnerability privately. Release preparation, GitHub settings and PyPI setup are documented in docs/releasing.md.
Metadata
Release files for mortis-engine 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mortis_engine-0.1.0.tar.gz | 345.3 kB | With provenance | Details for mortis_engine-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mortis_engine-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for mortis_engine-0.1.0-py3-none-any.whl |
Total release size: 542.8 kB
Release files / mortis_engine-0.1.0.tar.gz
| Download URL | mortis_engine-0.1.0.tar.gz |
|---|---|
| Size | 345.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
25241fddd3ecd50ac22caa59357d43d3565283301de8c3060ae91848e3d74165
|
|
BLAKE2b-256 checksum How to use checksums |
02b685866433cfcd220833a4c424e3031ee4dafe937433f6386d16fcebb71744
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / mortis_engine-0.1.0-py3-none-any.whl
| Download URL | mortis_engine-0.1.0-py3-none-any.whl |
|---|---|
| Size | 197.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d2d34953fab63a2cea8777169d25f0e2a45e9a2601afdc76b1fd6167b1aab76d
|
|
BLAKE2b-256 checksum How to use checksums |
9ce2a134f97c346c1344034647f44605946a10dc2a12385ed66f327240c7d08b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for mortis-engine 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mortis_engine-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.