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
• What you get
• Platforms and languages
• Why Modus
• How it works
• Knowledge model
• Code architecture
• Commands and workflows
• Development and contribution

Get started in 30 seconds

1. Install the CLI

The recommended installation is an isolated uv tool:

uv tool install openmodus

pipx install openmodus

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:

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

2. Connect a project

Run this inside the target repository:

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:

modus init --all-platforms

3. Author project knowledge

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

/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:

.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

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

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

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

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.

[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.

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.

The evidence, authoring, and integrity boundary explains why machine evidence, agent judgment, reviewable Markdown contracts, integrity checks, and safe publication remain separate.

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))

Commands and workflows

CLI commands

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

Useful inspections:

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.

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:

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.