Modus

Modus turns a repository and its business material into reviewable, source-grounded Markdown knowledge for coding agents.

The first open-source release keeps one durable product: authored knowledge. Source graphs are not a second database. During /modus-init or /modus-reinit, a disposable analyzer builds an in-memory evidence graph, projects the evidence needed for authoring, and then releases its working state.

Design

repository bytes + build context
              │ freeze
              ▼
      CST / structural IR
              │
       project binding
              │
   compiler observations (optional)
              │
   explicit semantic reconciliation
              │
      in-memory evidence graph
              │ project
              ▼
 deterministic JSON evidence bundle
              │ current init/reinit only
              ▼
 reviewed Markdown knowledge

This separation is intentional:

• source bytes and build configuration answer which code was analyzed;
• CST, project binding, and compiler observations retain their own provenance;
• exact, candidate, heuristic, and unresolved relationships stay distinct;
• conflicts become diagnostics instead of being overwritten;
• a method witness points back to source rather than copying method bodies;
• business domains and modules remain an agent-and-user judgment, never a clustering side effect.

Ordinary knowledge use, hooks, status, and incremental updates read current source and authored Markdown only. They cannot import or read initialization analysis.

Product surface

Modus installs exactly five knowledge skills:

• using-modus progressively adds project evidence only when the task needs it;
• modus-init and modus-reinit create or fully refresh authored knowledge;
• modus-update-knowledge performs an explicitly requested scoped update;
• modus-sync-knowledge silently revises knowledge only after a code change actually changes durable semantics or source anchors.

The first three authoring workflows are exposed as /modus-init, /modus-reinit, and /modus-update-knowledge. using-modus and modus-sync-knowledge are agent lifecycle helpers, not extra user workflows. Unrelated conversations never inspect Modus state.

The project layout keeps control and data ownership visibly separate:

.modus/            config, manifest, neutral skills/commands, hooks
modus/knowledge/   the only durable product data
modus/.cache/      disposable analysis and authoring state, created on demand

No other top-level entry belongs under modus/.

Evidence bundle

Each successful build publishes one immutable bundle:

modus/.cache/init-analysis/bundles/<bundleDigest>/
    ├── manifest.json
    ├── snapshot/{index.json,sources/,build-units/}
    ├── scope/{index.json,candidates/}
    ├── services/{index.json,boundaries/}
    ├── diagnostics.json
    └── evidence/{index.json,files/}

Each namespace is a bounded stable-key range catalog. Source files, build units, technical candidates, service boundaries, and evidence records have independent shards. Scope exposes explainable technical signals and navigation, never business names or conclusions.

The bundle contract has no absolute paths, timestamps, random IDs, raw graph, SQL database, WAL, historical generation, full-text index, or query language. JSON is stable-sorted UTF-8 with an explicit schema version.

Publication occurs in a same-filesystem temporary directory. The manifest binds exactly five Merkle roots; recursive validation rejects bad catalogs, records, references, paths, digests, and orphan shards before atomic rename. Current initialization consumes only the BuildReceipt returned by its own invocation.

Commands

The supported CLI is deliberately small:

modus init
modus update
modus help
modus uninstall
modus status
modus --version

modus uninstall removes managed project integration and the local CLI after showing a preview. Authored knowledge under modus/knowledge is retained by default; deleting that durable data requires the explicit modus uninstall --delete-knowledge option.

Initialization Skills use one internal adapter:

modus internal init-analysis build --root . --compiler auto --json
modus internal init-analysis select --root . --bundle-digest <digest> --source-snapshot-digest <digest> --view scope|services|evidence --json

The command is synchronous. Progress is written to stderr; JSON stdout contains only the bundle digest, source-snapshot digest, coverage, and diagnostics summaries. Select returns complete records under a byte/item budget and an optional stable cursor. There is no graph update/status/query/export/doctor or persisted progress command.

The design is informed by public ideas from CodeWiki, Aider, GitNexus, Repomix, and OpenDeepWiki, while the implementation, contracts, tests, prompts, and assets are independently authored for Modus. No source code from those projects is included.

Failure semantics

Snapshot drift, an invalid manifest, a digest mismatch, or cross-bundle mixing fails the current analysis. A failed build does not replace the last complete bundle, but the current init/reinit also does not consume that older bundle. It immediately continues from current source and user material.

A local parser or compiler-provider failure lowers only the affected evidence. It never means the repository has no business behavior. Compiler observations cannot silently overwrite CST or project binding; reconciliation retains the chosen result, alternatives, reason, context, and source witness.

Workspace semantics

A workspace root never runs initialization analysis. When a user chooses to initialize members that have no authored knowledge, each member runs as an independent single repository. Bundle identities and evidence never cross member roots.

Installation

Modus is distributed on PyPI as openmodus, while the installed command and Python import remain modus:

uv tool install openmodus
modus --version
modus init

Python 3.11 or newer is required.

Development

The package supports Python 3.11–3.14.

uv sync --locked --extra test
uv run pytest
uv run ruff check .
uv run mypy
uv build

The architecture boundary test rejects imports of modus.init_analysis from ordinary runtime packages. Distribution checks also reject legacy modus.graph, SQLite stores, WAL/query code, and obsolete graph commands.

The public application boundary is intentionally narrow:

from modus.init_analysis import BuildOptions, EvidenceRequest
from modus.init_analysis import build, open_bundle, select

receipt = build(".", BuildOptions(compiler_mode="auto"))
bundle = open_bundle(
    ".",
    receipt.bundle_digest,
    receipt.source_snapshot_digest,
)
scope = select(bundle, EvidenceRequest(view="scope"))

Everything behind these calls is implementation detail. This keeps the first release understandable today and leaves future machine-query capabilities free to earn their own explicit product contract later.