CausalityOS

CausalityOS is a terminal-first developer tool for investigating why software projects behave differently after code, test, log, or Git history changes.

Current release: 0.10.0

Installation

After publication to PyPI:

python -m pip install causalityos

For local development from this repository:

python -m pip install -e ".[dev]"

First Commands

causality --help
causality --version
causality analyze .

The PyPI distribution is named causalityos. The Python import package and CLI module remain named causality:

import causality

print(causality.__version__)

CLI Overview

causality analyze .
causality investigate .
causality reason .
causality verify . --dry-run
causality causal . --json
causality diagnose .
causality fix .
causality llm status

Core command groups:

• analyze: project structure, language counts, Git summary, code summary, and test discovery.
• git: recent commits, commit details, file history, hotspots, and repository stats.
• code: Python AST summaries, dependency graph, and impact analysis.
• tests: pytest discovery, test execution, and test history.
• logs: log level counting and error pattern fingerprinting.
• investigate: multi-layer evidence collection.
• reason: deterministic, evidence-grounded root-cause hypotheses.
• verify: isolated Git worktree counterfactual verification.
• causal: multi-evidence causal correlation.
• diagnose: end-to-end autonomous diagnosis.
• fix: autonomous repair proposal and isolated repair experiment.
• llm: local LLM provider status.

Configuration

CausalityOS has no required API keys. The optional local LLM explanation layer uses Ollama through Python standard-library HTTP calls.

Optional environment variables:

• CAUSALITY_LLM_PROVIDER: ollama by default, or mock for tests.
• CAUSALITY_LLM_HOST: defaults to http://localhost:11434.
• CAUSALITY_LLM_MODEL: defaults to qwen2.5:3b.
• CAUSALITY_LLM_TIMEOUT: request timeout in seconds.

To use local LLM explanations, install Ollama separately and pull the configured model:

ollama pull qwen2.5:3b
causality llm status

Deterministic analysis works without Ollama.

Runtime Requirements

• Python 3.11 or newer
• Runtime Python packages: typer, rich
• External command-line tools for selected features:
  • git for Git intelligence and counterfactual worktrees
  • pytest in the analyzed project environment when running causality tests run, verify, diagnose, or fix

Development extras are separate from runtime dependencies:

python -m pip install -e ".[test]"
python -m pip install -e ".[dev]"

Release Build

Build local distributions:

python -m build

Install a generated wheel into a clean environment:

python -m pip install dist/causalityos-0.10.0-py3-none-any.whl

Safety Model

CausalityOS avoids modifying the user's main working tree during analysis and verification. Counterfactual experiments use isolated Git worktrees or temporary directories. The fix command runs in safe mode by default and only applies a verified repair when --apply is explicitly passed.

Supported Platforms

CausalityOS is intended to run on Windows, macOS, and Linux with Python 3.11+. The code uses pathlib and platform-independent subprocess APIs.

Limitations

• Python code intelligence is currently AST-based static analysis.
• Runtime test intelligence uses pytest.
• Git-dependent commands require a Git executable on PATH.
• LLM explanations require a separately installed local Ollama service.

License

license = "MIT"