Metadata-Version: 2.4
Name: loomstate
Version: 0.1.1
Summary: The knowledge layer between your codebase and every AI that works on it.
Author: Sohaib Chebah
License-Expression: MIT
Project-URL: Homepage, https://github.com/sohaibchebah/loomstate
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: GitPython>=3.1
Requires-Dist: openai>=1.0
Requires-Dist: mcp<2,>=1.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.0
Dynamic: license-file

# LoomState

> **The knowledge layer between your codebase and every AI that works on it.**

Git versions your code.

**LoomState versions your project's knowledge.**

Modern AI coding assistants are excellent at writing code, but every one of them starts by rebuilding an understanding of your project. That process is repeated by every assistant, every session, and every new developer.

LoomState solves this by creating a shared, provenance-tracked knowledge layer that any AI can use.

Instead of asking an AI to rediscover your architecture, LoomState understands your repository once and makes that understanding reusable across ChatGPT, Claude, Codex, Cursor, Claude Code, and any MCP-compatible client.

---

# Why LoomState?

A software project contains more than source code.

It also contains:

- Architecture
- Design decisions
- Developer reasoning
- Investigation notes
- Known issues
- Current work
- Onboarding knowledge

Today that knowledge is scattered across conversations, documents, commits, and people's heads.

LoomState keeps it in one place.

---

# Core Principles

## Provenance First

Every piece of information records where it came from.

Examples:

- Git
- Human
- ChatGPT
- Claude
- Codex
- Repository Analysis

Nothing is anonymous.

Nothing pretends to be a fact without evidence.

---

## Facts and Reasoning Stay Separate

LoomState never mixes repository facts with AI-generated understanding.

Project facts remain deterministic.

AI-generated artifacts remain clearly identified.

Human reasoning remains searchable.

---

## Built for Multiple AI Assistants

LoomState is not tied to one model.

The same project knowledge can be consumed by:

- ChatGPT
- Claude
- Claude Code
- Codex
- Cursor
- Any MCP-compatible client

---

# Features

## Project State

```bash
loom sync
```

Build a deterministic snapshot of the repository.

Examples:

- Git information
- Languages
- Frameworks
- Dependencies
- Project structure
- Repository metadata

---

## Session Notes

```bash
loom note
```

Capture knowledge that source code cannot explain.

Examples:

- Current investigation
- Problems discovered
- Design discussions
- Progress updates
- Future work
- Important decisions

Every note records its author and provenance.

---

## Architecture Understanding

```bash
loom artifact architecture
```

Generate an evidence-backed architectural understanding of the project.

LoomState combines deterministic repository analysis with AI reasoning to produce:

- Project overview
- Execution flows
- Component summaries
- Architecture decisions
- Dependency relationships
- Entry points
- Evidence
- Confidence levels
- Unknowns

The generated artifact is version-aware and automatically detects when it becomes stale after repository changes.

---

## Knowledge Search

Search project knowledge instead of searching raw files.

Find:

- Architecture
- Notes
- Decisions
- Components
- Previous investigations

---

## MCP Server

Expose LoomState through the Model Context Protocol.

AI assistants can retrieve project knowledge directly without rebuilding project context from scratch.

---

## Multi-Project Support

Register multiple repositories and switch project context easily.

Perfect for developers working across several codebases.

---

## Onboarding

Generate a concise onboarding package for new developers or AI assistants.

Instead of scanning thousands of files, an assistant can understand the project in seconds.

---

# Installation

```bash
pip install loomstate
```

---

# Quick Start

Initialize LoomState inside a project:

```bash
loom init
```

Sync repository facts:

```bash
loom sync
```

Capture today's work:

```bash
loom note
```

Generate an architecture artifact:

```bash
loom artifact architecture
```

Check freshness:

```bash
loom status
```

Generate an onboarding package:

```bash
loom onboard
```

---

# Vision

LoomState is evolving from a CLI into a **Project Understanding Engine**.

Its long-term goal is to build a reusable knowledge model of a software project that can power:

- AI onboarding
- Knowledge search
- Architecture documentation
- Engineering documentation
- Team collaboration
- Faster developer onboarding
- Better AI-assisted software development

Instead of every AI rebuilding its own understanding of your project, LoomState allows every AI—and every developer—to start from the same trusted knowledge.
