Metadata-Version: 2.4
Name: loomstate
Version: 0.1.2
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

> **Understand your project once. Share that understanding with every AI.**

Git versions your code.

**LoomState versions your context.**

Modern AI assistants repeatedly rebuild the same understanding of your project, your coding preferences, and your team's conventions.

LoomState creates a shared context layer that every AI assistant can reuse.

Instead of every assistant starting from zero, they all start with the same trusted understanding.

---

# The Vision

LoomState is building a **Shared Context Platform** for software engineering.

```
                LoomState

        ┌──────────────────────┐
        │   Project Context    │
        ├──────────────────────┤
        │   Personal Context   │
        ├──────────────────────┤
        │     Team Context     │
        └──────────────────────┘

        Shared by Every AI Assistant
```

Whether you're using ChatGPT, Claude, Codex, Cursor, Claude Code or any future AI, they should all start from the same context instead of rebuilding it every session.

---

# Context Types

## 📦 Project Context

Everything about the software itself.

### Project State

Deterministic facts extracted directly from the repository.

Examples

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

Generate it:

```bash
loom sync
```

---

### Project Knowledge

Structured understanding built from static analysis.

Examples

- Components
- Entry points
- Execution flows
- Dependencies
- Ownership
- Architecture decisions

Search it:

```bash
loom search
```

---

### Project Artifacts

Human-readable AI-generated documents built from Project Knowledge.

Examples

- Architecture Summary
- AI Onboarding Package
- Project Documentation

Generate them:

```bash
loom artifact architecture

loom onboard
```

---

## 👤 Personal Context

Everything about how an individual developer prefers to work.

Examples

- Coding style
- Architecture preferences
- AI interaction preferences
- Language preferences
- Development habits

Examples

```bash
loom memory set coding-style

loom memory set ai-preferences

loom memory
```

Every AI assistant should respect the same preferences.

---

## 👥 Team Context

Knowledge shared by everyone working on the project.

Examples

- Team conventions
- Shared practices
- Current investigations
- Progress updates
- Architecture discussions
- Future roadmap

Capture new knowledge

```bash
loom note
```

Search team knowledge

```bash
loom search authentication
```

---

# MCP Server

LoomState exposes all context through the Model Context Protocol.

Start the server

```bash
loom-mcp
```

The MCP server allows AI assistants to retrieve context instead of rebuilding it.

Current tools

- get_project_state
- get_architecture_summary
- get_session_notes
- write_session_note
- knowledge_search

Future

- get_project_knowledge
- get_team_context
- get_personal_context

---

# Remote Access

Expose your local MCP server.

Start the server

```bash
loom-mcp
```

Open a tunnel

```bash
ngrok http 8000
```

Use the generated HTTPS URL in your AI client.

---

# Installation

```bash
pip install loomstate
```

---

# Quick Start

Initialize LoomState

```bash
loom init
```

Sync repository facts

```bash
loom sync
```

Record today's work

```bash
loom note
```

Generate architecture

```bash
loom artifact architecture
```

Generate onboarding

```bash
loom onboard
```

Start the MCP server

```bash
loom-mcp
```

---

# Why LoomState?

Today's AI assistants all maintain isolated memory.

```
ChatGPT
    │
    ├── Project Memory

Claude
    │
    ├── Project Memory

Codex
    │
    ├── Project Memory
```

Every assistant rebuilds the same understanding.

LoomState changes the model.

```
                LoomState

        Shared Project Context
        Shared Personal Context
        Shared Team Context

         ↙      ↓       ↘

     ChatGPT Claude Codex Cursor
```

One source of truth.

Every AI starts from the same understanding.

---

# Roadmap

## ✅ Current

- Project State
- Session Notes
- Architecture Artifacts
- Multi-project support
- MCP Server
- Knowledge Search
- AI Onboarding

---

## 🚧 In Progress

- Project Knowledge Model
- Component Index
- Architecture Graph
- Smarter Knowledge Retrieval
- Incremental Analysis

---

## 🔮 Future

### Personal Context

```bash
loom memory
```

Shared preferences across every AI assistant.

---

### Team Context

Rich collaborative knowledge shared by every developer.

---

### AI Context Exchange

Allow ChatGPT, Claude, Codex, Cursor and future assistants to share the same context automatically.

---

# Philosophy

Git versions your code.

LoomState versions everything else.

- Project Context
- Personal Context
- Team Context

One shared context.

Every AI.

Every developer.

Every project.
