Metadata-Version: 2.5
Name: openmodus
Version: 0.0.2
Summary: Evidence-backed authored knowledge for coding agents.
Author: Modus contributors
License-Expression: MIT
License-File: LICENSE
Keywords: code-intelligence,coding-agents,developer-tools,knowledge-management,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: click<8.4,>=8.1.0
Requires-Dist: jsonschema<5.0,>=4.0
Requires-Dist: networkx<4.0,>=3.4
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: questionary<3.0,>=2.1
Requires-Dist: tree-sitter-c-sharp<0.25,>=0.23
Requires-Dist: tree-sitter-c<0.25,>=0.23
Requires-Dist: tree-sitter-cpp<0.25,>=0.23
Requires-Dist: tree-sitter-go<0.26,>=0.23
Requires-Dist: tree-sitter-java<0.25,>=0.23
Requires-Dist: tree-sitter-javascript<0.26,>=0.23
Requires-Dist: tree-sitter-kotlin<2.0,>=1.0
Requires-Dist: tree-sitter-php<0.25,>=0.23
Requires-Dist: tree-sitter-python<0.26,>=0.23
Requires-Dist: tree-sitter-rust<0.25,>=0.23
Requires-Dist: tree-sitter-typescript<0.25,>=0.23
Requires-Dist: tree-sitter<0.26,>=0.23.0
Requires-Dist: typer<0.26,>=0.12.0
Provides-Extra: test
Requires-Dist: coverage[toml]<8.0,>=7.0; extra == 'test'
Requires-Dist: mypy<3.0,>=1.19; extra == 'test'
Requires-Dist: pytest<10.0,>=7.0; extra == 'test'
Requires-Dist: ruff<1.0,>=0.5.0; extra == 'test'
Requires-Dist: types-jsonschema<5.0,>=4.0; extra == 'test'
Requires-Dist: types-networkx<4.0,>=3.4; extra == 'test'
Requires-Dist: types-pyyaml<7.0,>=6.0; extra == 'test'
Description-Content-Type: text/markdown

<div align="center">

# Modus

**Turn source code, business material, and team constraints into reviewable, traceable, continuously maintained Markdown knowledge.**

Give coding agents more than files and symbols: give them the reasons behind the design, the way the business works, and the boundaries a change must preserve.

Already installed? Run `modus update`

<p>
  <img src="https://img.shields.io/badge/Claude_Code-supported-D97757?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude Code" />
  <img src="https://img.shields.io/badge/Codex-supported-111111?style=for-the-badge&logo=openai&logoColor=white" alt="Codex" />
  <img src="https://img.shields.io/badge/Cursor-supported-111111?style=for-the-badge" alt="Cursor" />
  <img src="https://img.shields.io/badge/CodeBuddy-supported-1F6FEB?style=for-the-badge" alt="CodeBuddy" />
</p>

[简体中文](../README.md) · [**English**](README.en.md)

[![PyPI](https://img.shields.io/pypi/v/openmodus?label=PyPI&color=3775A9)](https://pypi.org/project/openmodus/)
![Python](https://img.shields.io/badge/Python-3.11%E2%80%933.14-3776AB?logo=python&logoColor=white)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](../LICENSE)

</div>

---

You have just inherited a real project. Source code can tell an agent how the system works today, but it rarely explains the whole story: who a capability serves, why a rule exists, how failure is recovered, which interfaces must remain stable, or how earlier business decisions shaped the current design.

Modus turns that scattered evidence into reviewable knowledge inside the repository. The relevant parts enter an agent's context only when a task needs them, and durable semantic changes trigger the smallest necessary revision. Modus does not treat a source graph as a second database of truth: **Markdown knowledge is the durable product; graphs and evidence bundles are disposable authoring infrastructure.**

## Contents

- [Get started in 30 seconds](#get-started-in-30-seconds)
- [What you get](#what-you-get)
- [Platforms and languages](#platforms-and-languages)
- [Why Modus](#why-modus)
- [How it works](#how-it-works)
- [Knowledge model](#knowledge-model)
- [Code architecture](#code-architecture)
- [Commands and workflows](#commands-and-workflows)
- [Development and contribution](#development-and-contribution)

## Get started in 30 seconds

### 1. Install the CLI

The recommended installation is an isolated [`uv`](https://docs.astral.sh/uv/) tool:

```bash
uv tool install openmodus
```

<details>
<summary><strong>Install with pipx</strong></summary>

```bash
pipx install openmodus
```

</details>

Modus supports Python 3.11–3.14. The public PyPI distribution is named `openmodus`; the installed command and Python import remain `modus`. No private package index is required. If your machine uses a custom index that does not proxy public PyPI, select the public default index explicitly:

```bash
uv tool install --default-index https://pypi.org/simple openmodus
```

### 2. Connect a project

Run this inside the target repository:

```bash
cd path/to/your-project
modus init
```

The first run lets you select Claude Code, Codex, Cursor, or CodeBuddy, then projects the same neutral Skill contracts into the chosen hosts. To connect every supported host at once, run:

```bash
modus init --all-platforms
```

### 3. Author project knowledge

Return to your AI coding environment and invoke this workflow in the agent conversation:

```text
/modus-init
```

`modus init` is a Shell installation command. `/modus-init` is an Agent Skill workflow that authors knowledge. If a host exposes Skills by name instead of slash commands, ask it to “use modus-init to initialize knowledge for this project.”

After the first authoring run, the important repository boundaries are:

```text
.modus/                         platform-neutral control plane
├── skills/                     neutral source for five knowledge Skills
├── commands/                   explicit workflow entry points
├── hooks/                      session lifecycle integration
└── manifest.json               installation and upgrade ownership

modus/
├── knowledge/                  the only durable product data: reviewable Markdown
│   ├── architecture-overview.md
│   ├── constraint/
│   └── domain/
└── .cache/                     disposable analysis and authoring state, created on demand
```

## What you get

| Capability | How Modus approaches it |
| --- | --- |
| Source and business material together | Uses source, build context, tests, configuration, and user-provided material without erasing provenance boundaries. |
| Reviewable, durable knowledge | Produces structured Markdown in the repository instead of a private index readable by only one service. |
| Progressive context | `using-modus` reads only the relevant Domains, Modules, constraints, and current source when a task needs project facts. |
| Minimal maintenance after changes | `modus-sync-knowledge` revises affected prose only when responsibilities, contracts, rules, resources, or source anchors changed durably. |
| Consistent cross-host behavior | Projects one canonical Skill contract into Claude Code, Codex, Cursor, and CodeBuddy while isolating host differences in adapters. |
| Explainable degradation | Reports precise parser, compiler-provider, and evidence gaps, then continues with current source and readable material. |

Modus requires no remote knowledge service, vector database, or persistent source graph. Initialization analysis produces bounded local evidence for the current authoring run; ordinary tasks use current source and reviewed Markdown directly.

## Platforms and languages

### Coding-agent platforms

<p align="center">
  <img src="https://img.shields.io/badge/Claude_Code-Agent_Skills-D97757?logo=anthropic&logoColor=white" alt="Claude Code Agent Skills" />
  <img src="https://img.shields.io/badge/Codex-Agent_Skills-111111?logo=openai&logoColor=white" alt="Codex Agent Skills" />
  <img src="https://img.shields.io/badge/Cursor-Skills_%26_Rules-111111" alt="Cursor Skills and Rules" />
  <img src="https://img.shields.io/badge/CodeBuddy-Skills_%26_Commands-1F6FEB" alt="CodeBuddy Skills and Commands" />
</p>

Each adapter declares its Skill directory, resident instructions, and Hook layout. The shared installer owns deterministic writes, the ownership manifest, upgrade reconciliation, and safe uninstall behavior.

### Language capabilities

Evidence depth is explicit. Recognizing a file extension is never presented as complete semantic support.

**Compiler or type-system enhancement**

<p align="center">
  <img src="https://img.shields.io/badge/Python-semantic-3776AB?logo=python&logoColor=white" alt="Python semantic provider" />
  <img src="https://img.shields.io/badge/Java-semantic-ED8B00?logo=openjdk&logoColor=white" alt="Java semantic provider" />
  <img src="https://img.shields.io/badge/Go-semantic-00ADD8?logo=go&logoColor=white" alt="Go semantic provider" />
  <img src="https://img.shields.io/badge/C%2FC%2B%2B-semantic-00599C?logo=cplusplus&logoColor=white" alt="C and C++ semantic provider" />
  <img src="https://img.shields.io/badge/TypeScript-semantic-3178C6?logo=typescript&logoColor=white" alt="TypeScript semantic provider" />
</p>

Python, Java, Go, C/C++, and TypeScript can add local compiler or type-checker observations to structural evidence. An unavailable toolchain lowers only the affected evidence; it does not block the whole project.

**Dedicated structural extraction**

<p align="center">
  <img src="https://img.shields.io/badge/JavaScript%20%2F%20TypeScript-structure-F7DF1E?logo=javascript&logoColor=111111" alt="JavaScript and TypeScript" />
  <img src="https://img.shields.io/badge/Java-structure-ED8B00?logo=openjdk&logoColor=white" alt="Java" />
  <img src="https://img.shields.io/badge/Kotlin-structure-7F52FF?logo=kotlin&logoColor=white" alt="Kotlin" />
  <img src="https://img.shields.io/badge/Python-structure-3776AB?logo=python&logoColor=white" alt="Python" />
  <img src="https://img.shields.io/badge/Go-structure-00ADD8?logo=go&logoColor=white" alt="Go" />
  <img src="https://img.shields.io/badge/PHP-structure-777BB4?logo=php&logoColor=white" alt="PHP" />
  <img src="https://img.shields.io/badge/C%2FC%2B%2B-structure-00599C?logo=cplusplus&logoColor=white" alt="C and C++" />
  <img src="https://img.shields.io/badge/C%23%20%2F%20.NET-structure-512BD4?logo=dotnet&logoColor=white" alt="C sharp and .NET" />
  <img src="https://img.shields.io/badge/Rust-structure-000000?logo=rust&logoColor=white" alt="Rust" />
  <img src="https://img.shields.io/badge/Astro%20%2F%20Svelte-template-FF5D01?logo=astro&logoColor=white" alt="Astro and Svelte templates" />
</p>

Other registered source, template, configuration, data-definition, and document formats still enter a bounded generic-evidence path. Modus preserves coverage gaps instead of interpreting a missing provider as proof that the repository has no business behavior.

## Why Modus

Coding agents are good at finding files and explaining local implementation, but durable project understanding repeatedly encounters three problems:

1. **Every task rediscovers the system.** Entry points, relationships, rules, and verification paths are derived in one session and reconstructed again in the next.
2. **Structure is not meaning.** Imports, call edges, and directory clusters help navigation, but they cannot prove a business boundary, design rationale, or recovery policy.
3. **Documentation drifts away from implementation.** Knowledge without ownership, source anchors, and a maintenance lifecycle becomes silently untrue after code changes.

Modus does not answer by creating another database that must remain synchronized. It creates an inspectable knowledge-production and maintenance path:

- **Machines provide evidence; people and agents make judgments.** Structural analysis says where to look. Formal prose can state a conclusion only after rereading source, tests, configuration, or supplied material.
- **Knowledge follows software-engineering boundaries.** A system overview connects the architecture; Domains express business capabilities; Modules explain responsibilities and scenarios; topic documents own interfaces, objects, rules, state, dependencies, and infrastructure; constraint documents retain team practice.
- **Authoring and use are separate.** Repository-wide analysis exists only for init/reinit. Ordinary use never reads initialization caches or turns a disposable graph into a runtime dependency.
- **Maintenance belongs to the lifecycle.** A modifying task checks only for durable knowledge impact and performs a minimal revision when that impact is real, avoiding documentation churn on every edit.

## How it works

Modus keeps one-off machine analysis separate from durable knowledge. `init/reinit` builds verifiable code evidence for the current authoring run; agents and people interpret that evidence together with business material and current source. Ordinary tasks consume reviewed Markdown and return to the implementation whenever a conclusion must be verified.

```text
[One-off evidence production: init / reinit]
  source + build files + tests/configuration
    → Source Snapshot (freeze this run's repository inputs)
    → CST / structural IR / project binding
    → optional compiler and type-system observations
    → explicit semantic reconciliation → temporary evidence graph
    → entry / relation / effect / resource IR
    → deterministic, bounded JSON bundle ───────────────┐
                                                        │
[Knowledge authoring]                                  ▼
  business material + team constraints ─→ agent + human judgment ← current source
                                                        │
                                                        ▼
                                      reviewable, source-grounded Markdown
                                                        │
[Continuous use and maintenance]                        │
  ordinary task ─→ progressive routing and retrieval ───┤→ act after source check
  code change ─→ durable-knowledge impact decision ─→ minimal revision if needed
```

These are three decoupled phases. Evidence production runs only during `init/reinit`; authoring never promotes a machine relationship directly into a business conclusion; continuous use and maintenance neither rebuild initialization analysis nor create documentation churn for every code edit.

The full lifecycle deliberately protects three boundaries:

- **Evidence guides; it does not decide.** `exact`, `candidate`, `heuristic`, and `unresolved` remain distinct. Conflicts become diagnostics, and an agent must reread source, tests, configuration, or supplied material before stating a conclusion.
- **Analysis state is not the durable product.** The temporary graph is released after projection, and the JSON bundle lives in disposable cache for the current authoring run only. Ordinary tasks never read it; only reviewed Markdown becomes lasting knowledge.
- **Current source remains authoritative.** Snapshot drift or an integrity failure stops the current analysis, while a local parser or provider gap lowers only the affected evidence. Ordinary use and incremental maintenance read prose together with current source instead of silently falling back to an old conclusion.

## Knowledge model

The knowledge model is not a document tree grouped by file type. It combines four task-oriented views. They are perspectives for reading and modeling a project, not physical layers that every repository must reproduce.

| View | Question it answers | Primary carriers |
| --- | --- | --- |
| Business | Why is a change needed, and where do its concepts, scenarios, and experience belong? | Domain routing plus concepts, scenarios, and experience under `business/` |
| Architecture | What are the capability boundaries, and how do runtime units and modules collaborate? | The root overview, Domain boundaries, state, and downstream handoffs |
| System | How does one capability work, and how do contracts, objects, rules, and resources produce its result? | Module scenario guides and the six reusable topic documents |
| Engineering constraints | What must not change casually, and how is a change proved safe? | `constraint/`, rule and infrastructure topics, and Module implementation and verification entry points |

```text
modus/knowledge/
├── architecture-overview.md          project, runtime layers, capability relations, navigation
├── constraint/
│   ├── global-standard.md             global constraints
│   └── team-standard.md               architecture, change, and verification standards
└── domain/<domain>/
    ├── SKILL.md                       Domain routing and capability overview
    └── references/
        ├── modules/<module>.md        responsibilities, scenarios, tradeoffs, verification
        ├── api.md                     contract overview and stable navigation
        ├── api/                       optional semantic groups, never one shard per contract
        ├── object.md                  object overview and stable navigation
        ├── object/                    optional semantic groups, never one shard per DTO/class
        ├── rule.md                    rules, constraints, exceptions, and evidence
        ├── state_machine.md           state, flows, failures, and recovery
        ├── downstream.md              dependencies, events, and system handoffs
        ├── infrastructure.md          storage, configuration, processes, runtime resources
        └── business/                  human-owned business knowledge
            ├── index.md               business-knowledge entry point
            ├── meta/                  terminology, concepts, objects, measures, rules
            ├── experience/            decisions, practice, retrospectives, applicability
            └── scenario/              actors, flows, outcomes, and exceptional scenarios
```

Each carrier has a stable responsibility. A Domain is a capability and ownership boundary whose `SKILL.md` provides routing. A Module organizes the causal story around responsibilities and real scenarios. The six topic documents own the complete definitions of reusable facts, while the root overview connects system-wide capabilities and runtime architecture. Frontends, backends, CLIs, libraries, workers, data jobs, infrastructure, and plugins share this contract while expanding only the capability blocks that actually exist.

**Structure routes; prose explains.** Stable identities, source anchors, and precise links let an agent move progressively from the root overview into a Domain, Module, and relevant topics. Markdown explains business outcomes, decisions, completion boundaries, failure and recovery, and design tradeoffs. Method-level source evidence belongs only in Modules and topics; the root overview and Domain remain stable routers. One document owns the full definition of a fact; the rest link to it, so the entire knowledge base never has to be loaded at once.

Modus favors knowledge that is **highly reusable, high risk, or hard to infer** instead of generating a summary for every function. Public contracts, core objects, state transitions, downstream handoffs, compatibility boundaries, and verification standards merit durable treatment; routine implementation detail that is cheap to recover stays in source. `business/` and `constraint/` are human-owned by default, so automation cannot overwrite organizational knowledge with scan output. Changes to generated knowledge are guarded by read-time hashes and checked for path identity, link, and anchor integrity.

## Code architecture

Modus follows the boundaries it advocates: the entry surface stays narrow, application orchestration is separate from retrieval algorithms, declarative adapters contain host differences, and durable knowledge uses a different directory and write contract from disposable analysis state.

| Subsystem | Responsibility and boundary |
| --- | --- |
| [`modus.machine`](../src/modus/machine/README.md) | The machine layer: freezes inputs, observes facts and resolves relations along the N1-N6 lifecycle (corpus, facts, resolution, capability, projection, packet), publishing one immutable, bounded evidence bundle per init/reinit. |
| [`modus.orchestrator`](../src/modus/orchestrator/README.md) | Composes preflight, task context, and knowledge-impact candidates without owning retrieval algorithms or knowledge writes. |
| [`modus.retrieval`](../src/modus/retrieval/README.md) | Progressively selects prose, current source, and constraints under one deadline and output budget, reporting partial results explicitly. |
| `modus.platforms` / `modus.hooks` | Projects canonical Skills into four hosts while isolating host directories, resident instructions, and session Hooks. |
| [`modus.scaffold`](../src/modus/scaffold/README.md) | Packages neutral templates and owns deterministic installation, upgrade reconciliation, ownership records, and safe uninstall. |
| `knowledge_verification` / `knowledge_write_session` | Separate mechanical integrity checks, human ownership, compare-and-swap writes, and atomic publication. |

The [evidence, authoring, and integrity boundary](../docs/knowledge-lifecycle-boundary.md) explains why machine evidence, agent judgment, reviewable Markdown contracts, integrity checks, and safe publication remain separate.

<details>
<summary><strong>Maintainer deep dive: evidence bundles and integrity</strong></summary>

Every successful build publishes one immutable bundle identified by `bundleDigest`. Each namespace is a stable-key range catalog; globally sorted records are packed into content-addressed pages of at most 128 records and 256 KiB. The manifest binds five Merkle roots and the source-snapshot identity. Publication recursively validates catalogs, records, references, paths, digests, and orphan shards before an atomic same-filesystem rename.

The bundle stores no absolute paths, timestamps, random IDs, full raw graph, SQL database, WAL, historical generation, full-text index, or general-purpose query language. `query_evidence` range-routes by stable key and verifies only the index pages, data pages, and current source digests it traverses.

Initialization analysis deliberately exposes only four public Python operations:

```python
from modus.machine import AnalysisIdentity, AnalysisOptions, ContextRequest, EvidenceQuery
from modus.machine import TaskIntent, analyze_repository, build_authoring_context
from modus.machine import open_analysis, query_evidence

receipt = analyze_repository(".", AnalysisOptions(compiler_mode="auto"))
bundle = open_analysis(
    ".",
    AnalysisIdentity(receipt.bundle_digest, receipt.baseline_digest),
)
scope = query_evidence(bundle, EvidenceQuery(view="scope"))
context = build_authoring_context(bundle, ContextRequest(TaskIntent.SCOPE_DISCOVERY))
```

</details>

<details>
<summary><strong>Maintainer deep dive: failure semantics</strong></summary>

Source-snapshot drift, a missing manifest, a digest mismatch, or cross-bundle mixing stops the current analysis. A failed build does not replace the latest complete bundle, but the current init/reinit also does not consume that older bundle as if it described the current run; it immediately continues from current source and available material.

A local parser, project-binding, or compiler-provider failure lowers only the affected evidence. Reconciliation retains the chosen relationship, alternatives, reason, context, and source witness. Business conclusions that machine evidence cannot prove must be confirmed from first-party material by the author.

</details>

## Commands and workflows

### CLI commands

The CLI installs, maintains, and inspects Modus. Run `modus help` for the complete surface in the installed version.

| Command | Purpose |
| --- | --- |
| `modus init` | Install neutral project assets and project them into the selected coding-agent hosts. |
| `modus update` | Update the local CLI and reconcile Modus-managed Skills and Hooks in the current project. |
| `modus help` | Show CLI commands, explicit knowledge workflows, and automatic knowledge capabilities. |
| `modus uninstall` | Preview and remove the current project's managed assets by default; authored knowledge is retained and the personal CLI requires an explicit scope. |
| `modus status` | Read installation, version, and authored-knowledge status without reading initialization caches. |

Useful inspections:

```bash
modus status --json
modus update --dry-run
modus uninstall --dry-run
modus uninstall --project --delete-knowledge --dry-run
modus uninstall --person --dry-run
modus help /modus-init
```

`modus uninstall` targets only the current project by default. Add `--delete-knowledge`
to remove project knowledge, use `--person` for only the personal CLI, and pass `--all`
explicitly to target both project and personal installations.

### Explicit knowledge workflows

Use these entry points in an AI coding environment, not in a Shell.

| Workflow | When to use it |
| --- | --- |
| `/modus-init` | Create complete project knowledge from current code, build context, and material; automatically behaves as reinit when a formal Scope exists. |
| `/modus-reinit` | Reuse stable Domain and Module identities while fully reviewing and reorganizing existing prose. |
| `/modus-update-knowledge` | Update knowledge affected by explicit material or local facts without rerunning repository-wide analysis. |

### Automatic knowledge capabilities

- `using-modus` progressively loads knowledge only when a task needs project facts, then decides whether a modifying task caused durable knowledge impact.
- `modus-sync-knowledge` performs the smallest in-place, verifiable prose revision only after a positive impact decision.

These are agent lifecycle capabilities, not extra workflows that users must remember and invoke on every task.

## Development and contribution

Modus supports Python 3.11–3.14. Local development and CI use the same locked dependencies and quality gates:

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

When contributing, treat the CLI, Skills, schemas, and Markdown contracts as public interfaces. Behavioral changes should include focused tests, language-provider gaps must degrade explicitly, and host adapters must preserve shared ownership and uninstall semantics. Architecture-boundary tests prevent ordinary runtime code from depending on disposable initialization analysis and ensure release artifacts do not reintroduce legacy graph databases or removed commands.

## License

Modus is available under the [MIT License](../LICENSE).
