moolmesh 1.4.0__tar.gz

moolmesh-1.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MoolMesh contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

moolmesh-1.4.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: moolmesh
+Version: 1.4.0
+Summary: The context mesh for autonomous agents — unified observability, telemetry, and inter-agent coordination
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/fmicalizzi/moolmesh
+Project-URL: Repository, https://github.com/fmicalizzi/moolmesh
+Project-URL: Issues, https://github.com/fmicalizzi/moolmesh/issues
+Keywords: ai,agents,observability,telemetry,mcp,claude,codex,opencode,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file

moolmesh-1.4.0/README.md

@@ -0,0 +1,294 @@
+# MoolMesh
+
+**The context mesh for autonomous agents.**
+
+Unified observability, telemetry, and inter-agent coordination — running entirely on your machine.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://python.org)
+[![Tests: 509 passing](https://img.shields.io/badge/Tests-509%20passing-green.svg)](#development)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-brightgreen.svg)](#)
+[![Español](https://img.shields.io/badge/Docs-Espa%C3%B1ol-orange.svg)](README.es.md)
+
+---
+
+## Why MoolMesh?
+
+Modern software development isn't human-to-keyboard anymore. It's an ecosystem of AI agents working in parallel — each with its own logs, token counters, and reasoning traces, all locked in separate silos.
+
+When Claude Code gets stuck in a loop, your other agents don't know. When you spend tokens across four providers, you can't see which git commit justified it. When your team uses different AI tools on the same repo, nobody has the full picture.
+
+**MoolMesh congregates what is scattered.** It auto-discovers sessions from every major AI coding agent, normalizes them into a single queryable database, and exposes that state to both humans (via a dashboard) and machines (via MCP).
+
+Read our [Philosophy](PHILOSOPHY.md) to understand the dual axiom behind MoolMesh: **Human-First & Agent-First**.
+
+---
+
+## What You Get
+
+Four views in a single browser tab:
+
+| View | What it shows |
+|------|---------------|
+| **AI Sessions** | Live event feed from all agents — messages, tool calls, token usage, models |
+| **Analytics** | Token consumption by provider, hourly activity, top tools, top projects |
+| **Project Pulse** | PR kanban, issues list, milestones, GitHub Projects v2 board |
+| **Code Timeline** | Commit feed, author stats, hot files, daily/weekly digest narratives |
+
+Plus a **MCP server** that lets other AI agents query your session data programmatically — enabling agent-to-agent supervision and orchestration.
+
+---
+
+## Quick Start
+
+```bash
+# Install
+pip install moolmesh
+
+# Start the dashboard
+mool dashboard
+# → open http://localhost:5200
+```
+
+That's it. MoolMesh auto-discovers your AI sessions immediately. No configuration needed.
+
+> **Running from source:**
+> ```bash
+> git clone https://github.com/fmicalizzi/moolmesh.git
+> cd moolmesh
+> python -m venv .venv && source .venv/bin/activate
+> pip install -e ".[dev]"
+> mool dashboard
+> ```
+
+---
+
+## Supported Agents
+
+| Provider | Session source | Format |
+|----------|---------------|--------|
+| **Claude Code** | `~/.claude/projects/` | JSONL per session + subagent logs |
+| **Codex (GPT-5)** | `~/.codex/sessions/` + `state_5.sqlite` | Rollout JSONL + SQLite metadata |
+| **Qwen CLI** | `~/.qwen/projects/` | JSONL per chat |
+| **OpenCode** | `~/.local/share/opencode/opencode.db` | SQLite (session → message → part) |
+
+Sessions are auto-discovered on startup. No configuration, no API keys, no cloud services.
+
+---
+
+## Git & GitHub Integration
+
+Register a git repository to unlock Project Pulse and Code Timeline:
+
+```bash
+mool repo add /path/to/your/repo
+```
+
+This ingests commit history and starts polling GitHub for issues, PRs, milestones, and Projects v2.
+
+```bash
+mool repo list                           # Show registered repos
+mool repo remove /path/to/repo           # Unregister
+mool repo sync /path/to/repo --all       # Re-ingest full history
+```
+
+A GitHub token is resolved automatically: `gh auth token` → `GITHUB_TOKEN` env → `config.toml`. If you use the GitHub CLI, no extra setup is needed.
+
+---
+
+## MCP Server (Inter-Agent API)
+
+MoolMesh exposes a read-only MCP server over stdio, allowing any MCP-compatible agent to query session data:
+
+```json
+{
+  "mcpServers": {
+    "moolmesh": {
+      "command": "uv",
+      "args": ["run", "/path/to/moolmesh/hub/mcp_server.py"]
+    }
+  }
+}
+```
+
+Available tools:
+
+| Tool | Description |
+|------|-------------|
+| `get_recent_events` | Latest N events across all providers |
+| `get_active_sessions` | Sessions active in the last N hours |
+| `get_token_usage` | Token consumption by provider |
+| `get_tool_stats` | Top tools used by AI agents |
+| `search_events` | Full-text search on event summaries |
+| `get_project_activity` | Complete project summary with stats |
+
+Resources: `hub://schema` (database schema), `hub://projects` (project list with stats).
+
+The server opens SQLite in read-only mode (`?mode=ro`). It runs as a separate process (~15-20 MB RAM), independent from the dashboard.
+
+---
+
+## Digest Narratives
+
+Code Timeline generates daily and weekly digests for each registered repo:
+
+| Level | What | When |
+|-------|------|------|
+| **L1** | Raw SQL stats (commits, PRs, issues, LOC) | Always available |
+| **L2** | Structured template with bullet points | Always available |
+| **L3** | LLM-generated narrative paragraph | When an LLM provider is configured |
+
+L3 works with any OpenAI-compatible API. Configure in `~/.moolmesh/config.toml`:
+
+```toml
+[llm]
+provider = "openrouter"
+api_url  = "https://openrouter.ai/api/v1"
+model    = "google/gemma-4-31b-it:free"
+api_key  = "sk-or-v1-..."
+```
+
+Supported providers: OpenRouter, OpenAI, Together, Groq, Ollama. If the LLM is unavailable, digests fall back to L2 automatically.
+
+---
+
+## Batch Reports
+
+Generate Markdown analysis reports from the command line:
+
+```bash
+# Auto report — writes to ~/.moolmesh/reports/
+mool report auto
+
+# Full content (no truncation)
+mool report auto --complete
+
+# Filter by project or provider
+mool report --project myapp --provider claude --output ./exports
+```
+
+---
+
+## CLI Reference
+
+```
+mool <command> [options]
+
+Commands:
+  dashboard              Start the live monitoring dashboard
+  report                 Generate batch Markdown analysis reports
+  discover               List all discovered AI agent projects
+  repo add PATH          Register a git repo for monitoring
+  repo list              List registered repos with commit counts
+  repo remove PATH       Unregister a repo
+  repo sync PATH         Re-ingest commit history
+
+Dashboard options:
+  --port PORT            Server port (default: 5200)
+  --host HOST            Server host (default: localhost)
+  --project NAME         Filter to project name
+  --providers LIST       Comma-separated: claude,codex,qwen,opencode
+
+Report options:
+  --complete             Full-content mode: no truncation
+  --output DIR           Output directory
+  --provider PROVIDER    Filter by provider
+```
+
+---
+
+## Architecture
+
+```
+hub/
+  parsers/         JSONL + SQLite parsers for each provider
+  adapters/        Normalize provider entries → unified events
+  watchers/        File harvesters: discover → offset → parse → store → SSE
+  harvesters/      GitHarvester (120s) + GitHubHarvester (15s/60s)
+  integrations/    GitHubClient (REST + GraphQL) + LLM clients
+  digests/         L1 Stats → L2 Template → L3 LLM narrative
+  correlation/     AI ↔ Git links: Co-Author, issue refs, timestamps
+  dashboard/       HTTP server + SSE + 4 HTML pages
+  cache/           EventStore (events.db) + GitStore (github.db)
+  mcp_server.py    MCP stdio server (read-only, PEP 723 inline deps)
+  cli.py           CLI entry point
+```
+
+### How data flows
+
+1. **Discovery** scans provider directories for session files
+2. **Parsers** read JSONL or query SQLite into typed entries
+3. **Adapters** normalize to `UnifiedEvent` with common fields
+4. **Watchers** poll incrementally, store atomically in SQLite, push to SSE
+5. **Dashboard** serves live feed + analytics via HTTP + Server-Sent Events
+
+All state is persisted in SQLite. Crash-safe, exactly-once semantics via transactional offsets.
+
+---
+
+## Persistence
+
+| Database | Path | Contents |
+|----------|------|----------|
+| `events.db` | `~/.moolmesh/events.db` | AI session events, file offsets, SSE replay buffer |
+| `github.db` | `~/.moolmesh/github.db` | Repos, commits, issues, PRs, milestones, digests |
+
+Both databases are created automatically. Schema migrates on startup.
+
+---
+
+## Reliability
+
+- **Zero-gap SSE** — `id:` fields enable browser reconnection with replay from SQLite
+- **Transactional offsets** — events and file positions update in a single transaction
+- **Git crash safety** — exceptions caught per-repo, 60s timeout on `git fetch`
+- **GitHub ETags** — 304 responses don't consume rate limit
+- **Digest fallback** — LLM unavailable → L2 template, no repos → L1 stats
+- **OpenCode WAL safety** — read-only SQLite with timeout, never blocks OpenCode writes
+
+---
+
+## Roadmap
+
+MoolMesh started with coding agents but the vision is broader — any autonomous agent that generates observable signals belongs in the mesh.
+
+| Status | Scope | Details |
+|--------|-------|---------|
+| **Shipping** | Claude Code, Codex (GPT-5), Qwen CLI, OpenCode | Full session parsing, live monitoring, MCP |
+| **Planned** | Aider, Pi, GitHub Copilot CLI, Antigravity CLI | Adapters in progress — PRs welcome |
+| **Future** | Hermes, Odyssey, Goose, community requests | Open an issue to propose a new provider |
+| **Vision** | Cross-repo model usage analytics | Monitor AI token consumption and agent activity across an organization's repositories |
+
+The long-term goal: a unified observability layer for any agent ecosystem — coding, ops, research, orchestration — so teams can see what their agents are doing, what they're spending, and whether they're stepping on each other.
+
+---
+
+## Limitations
+
+- **macOS optimal, Linux supported** — macOS uses `kqueue` for instant detection; Linux uses polling (~1s)
+- **No authentication** — dashboard binds to localhost. Use a reverse proxy for remote access
+- **Single-user design** — not intended for multi-user or server deployment
+- **Python 3.11+** — uses `tomllib` from stdlib
+- **GitHub Projects v2 only** — classic Projects (v1) not supported
+
+---
+
+## Development
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ -v --cov=hub
+```
+
+509 tests. Zero external dependencies. Python stdlib + SQLite.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+[MIT](LICENSE) — Your telemetry is yours.

moolmesh-1.4.0/hub/__init__.py

@@ -0,0 +1,4 @@
+"""MoolMesh — the context mesh for AI coding agents."""
+
+__version__ = "1.4.0"
+USER_AGENT = f"moolmesh/{__version__}"

moolmesh-1.4.0/hub/__main__.py

@@ -0,0 +1,7 @@
+"""Allow `python -m hub` as a fallback entry point."""
+
+from hub.cli import main
+
+
+if __name__ == "__main__":
+    main()

moolmesh-1.4.0/hub/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .base import BaseAdapter
+
+__all__ = ["BaseAdapter"]

moolmesh-1.4.0/hub/adapters/base.py

@@ -0,0 +1,27 @@
+"""Abstract base adapter for converting provider entries to unified models."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from hub.models.base import UnifiedEvent, UnifiedMessage
+
+
+class BaseAdapter(ABC):
+
+    @abstractmethod
+    def to_unified(self, entry: Any, project: str) -> UnifiedMessage | None:
+        """Convert a provider-specific entry to UnifiedMessage.
+
+        Returns None if the entry should be skipped.
+        """
+        ...
+
+    @abstractmethod
+    def to_event(self, entry: Any, project: str) -> UnifiedEvent | None:
+        """Convert a provider-specific entry to a lightweight UnifiedEvent for SSE.
+
+        Returns None if the entry should be skipped.
+        """
+        ...

moolmesh-1.4.0/hub/adapters/claude_adapter.py

@@ -0,0 +1,238 @@
+"""Adapter converting Claude entries to unified models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from hub.adapters.base import BaseAdapter
+from hub.models.base import (
+    MessageRole,
+    Provider,
+    TokenUsage,
+    ToolCall,
+    UnifiedEvent,
+    UnifiedMessage,
+)
+from hub.models.claude import ClaudeContentBlock, ClaudeEntry, ClaudeUsage
+
+# Types we skip during adaptation
+_SKIP_TYPES = frozenset({"file-history-snapshot"})
+
+
+class ClaudeAdapter(BaseAdapter):
+
+    def to_unified(self, entry: ClaudeEntry, project: str) -> UnifiedMessage | None:
+        if entry.type in _SKIP_TYPES:
+            return None
+
+        role = self._map_role(entry)
+        if role is None:
+            return None
+
+        tool_calls = self._extract_tool_calls(entry.content_blocks)
+        tokens = self._map_usage(entry.usage)
+        timestamp = self._parse_timestamp(entry.timestamp)
+
+        return UnifiedMessage(
+            id=entry.uuid,
+            provider=Provider.CLAUDE,
+            session_id=entry.session_id,
+            project=project,
+            role=role,
+            text=entry.content_text,
+            tool_calls=tool_calls,
+            timestamp=timestamp,
+            model=entry.model,
+            tokens=tokens,
+            parent_id=entry.parent_uuid,
+            is_sidechain=entry.is_sidechain,
+            cwd=entry.cwd,
+            raw=entry.raw,
+        )
+
+    def to_event(self, entry: ClaudeEntry, project: str) -> UnifiedEvent | None:
+        if entry.type in _SKIP_TYPES:
+            return None
+
+        role = self._map_role(entry)
+        if role is None:
+            return None
+
+        summary = self._summarize(entry)
+        tokens = None
+        if entry.usage:
+            tokens = {
+                "input": entry.usage.input_tokens,
+                "output": entry.usage.output_tokens,
+            }
+
+        tool_name = None
+        file_path = None
+        for block in entry.content_blocks:
+            if block.type == "tool_use" and block.tool_name:
+                tool_name = block.tool_name
+                if block.tool_input:
+                    file_path = (
+                        block.tool_input.get("file_path")
+                        or block.tool_input.get("path")
+                        or block.tool_input.get("command", "")[:80]
+                    )
+                break
+
+        return UnifiedEvent(
+            provider=Provider.CLAUDE,
+            project=project,
+            event_type=role.value,
+            timestamp=entry.timestamp,
+            summary=summary,
+            session_id=entry.session_id,
+            tokens=tokens,
+            tool_name=tool_name,
+            file_path=str(file_path) if file_path else None,
+            model=entry.model,
+            cwd=entry.cwd or None,
+        )
+
+    def _map_role(self, entry: ClaudeEntry) -> MessageRole | None:
+        match entry.type:
+            case "user":
+                return MessageRole.USER
+            case "assistant":
+                # Check if this is primarily a tool_use or tool_result message
+                has_tool_use = any(
+                    b.type == "tool_use" for b in entry.content_blocks
+                )
+                has_tool_result = any(
+                    b.type == "tool_result" for b in entry.content_blocks
+                )
+                has_thinking = any(
+                    b.type == "thinking" for b in entry.content_blocks
+                )
+                has_text = bool(entry.content_text.strip())
+
+                if has_tool_result and not has_text:
+                    return MessageRole.TOOL_RESULT
+                if has_tool_use and not has_text:
+                    return MessageRole.TOOL_USE
+                if has_thinking and not has_text and not has_tool_use:
+                    return MessageRole.THINKING
+                return MessageRole.ASSISTANT
+            case "system":
+                return MessageRole.SYSTEM
+            case "summary":
+                return MessageRole.SUMMARY
+            case _:
+                return None
+
+    def _extract_tool_calls(
+        self, blocks: list[ClaudeContentBlock]
+    ) -> list[ToolCall]:
+        calls: list[ToolCall] = []
+        for block in blocks:
+            if block.type != "tool_use" or not block.tool_name:
+                continue
+            input_data = block.tool_input or {}
+            fp = input_data.get("file_path") or input_data.get("path")
+            op_type = self._infer_operation_type(block.tool_name, input_data)
+            calls.append(
+                ToolCall(
+                    name=block.tool_name,
+                    input_data=input_data,
+                    tool_id=block.tool_id,
+                    file_path=fp,
+                    operation_type=op_type,
+                )
+            )
+        return calls
+
+    def _map_usage(self, usage: ClaudeUsage | None) -> TokenUsage | None:
+        if usage is None:
+            return None
+        return TokenUsage(
+            input_tokens=usage.input_tokens,
+            output_tokens=usage.output_tokens,
+            cache_creation=usage.cache_creation_input_tokens,
+            cache_read=usage.cache_read_input_tokens,
+        )
+
+    def _summarize(self, entry: ClaudeEntry) -> str:
+        """Produce a human-readable one-liner for the event feed."""
+        match entry.type:
+            case "user":
+                text = entry.content_text.strip().replace("\n", " ")
+                return text[:120] if text else "[empty user message]"
+            case "assistant":
+                # Prioritize tool_use summaries
+                for block in entry.content_blocks:
+                    if block.type == "tool_use" and block.tool_name:
+                        brief = self._brief_tool_args(
+                            block.tool_name, block.tool_input
+                        )
+                        return f"{block.tool_name}: {brief}"
+                    if block.type == "thinking" and block.thinking:
+                        return f"[thinking] {block.thinking[:100]}"
+                text = entry.content_text.strip().replace("\n", " ")
+                return text[:120] if text else "[assistant response]"
+            case "system":
+                sub = f" ({entry.subtype})" if entry.subtype else ""
+                return f"[system{sub}]"
+            case "summary":
+                return "[context summary]"
+            case _:
+                return f"[{entry.type}]"
+
+    @staticmethod
+    def _brief_tool_args(tool_name: str, input_data: dict | None) -> str:
+        if not input_data:
+            return ""
+        match tool_name:
+            case "Bash":
+                cmd = input_data.get("command", "")
+                return cmd[:80]
+            case "Read":
+                return input_data.get("file_path", "")[:80]
+            case "Write" | "Edit" | "MultiEdit":
+                return input_data.get("file_path", "")[:80]
+            case "Glob":
+                return input_data.get("pattern", "")[:80]
+            case "Grep":
+                return input_data.get("pattern", "")[:80]
+            case "Agent":
+                return input_data.get("description", "")[:80]
+            case "WebSearch" | "WebFetch":
+                return input_data.get("query", input_data.get("url", ""))[:80]
+            case _:
+                # Generic: show first key=value
+                for k, v in input_data.items():
+                    return f"{k}={str(v)[:60]}"
+                return ""
+
+    @staticmethod
+    def _infer_operation_type(tool_name: str, input_data: dict) -> str | None:
+        match tool_name:
+            case "Read" | "Glob" | "Grep":
+                return "read"
+            case "Write":
+                return "create"
+            case "Edit" | "MultiEdit":
+                return "modify"
+            case "Bash":
+                cmd = input_data.get("command", "")
+                if any(k in cmd for k in ("rm ", "rm\t", "rmdir")):
+                    return "delete"
+                if any(k in cmd for k in ("mkdir", "touch", "cp ", "mv ")):
+                    return "create"
+                return "exec"
+            case "Agent":
+                return "exec"
+            case _:
+                return None
+
+    @staticmethod
+    def _parse_timestamp(ts: str) -> datetime | None:
+        if not ts:
+            return None
+        try:
+            return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        except (ValueError, TypeError):
+            return None