Metadata-Version: 2.4
Name: logthread
Version: 2.0.6
Summary: Log Thread — AI-powered code intelligence with graph context. Enables even smaller AI models to make accurate code changes by providing rich structural understanding of your codebase.
Project-URL: Homepage, https://logthread.dev
Author: Log Thread Team
License: UNLICENSED
Keywords: ai-code-editor,code-context,code-intelligence,knowledge-graph,logthread,mcp,static-analysis,tree-sitter
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.0
Requires-Dist: fastembed>=0.7.0
Requires-Dist: igraph>=1.0.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: leidenalg>=0.11.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pathspec>=1.0.4
Requires-Dist: real-ladybug>=0.11.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sqlglot>=25.0.0
Requires-Dist: sse-starlette>=2.0.0
Requires-Dist: tree-sitter-c-sharp>=0.23.0
Requires-Dist: tree-sitter-go>=0.23.0
Requires-Dist: tree-sitter-java>=0.23.0
Requires-Dist: tree-sitter-javascript>=0.23.0
Requires-Dist: tree-sitter-language-pack>=0.8.0
Requires-Dist: tree-sitter-python>=0.23.0
Requires-Dist: tree-sitter-ruby>=0.23.0
Requires-Dist: tree-sitter-typescript>=0.23.0
Requires-Dist: tree-sitter>=0.25.0
Requires-Dist: typer>=0.15.0
Requires-Dist: uvicorn[standard]>=0.34.0
Requires-Dist: watchfiles>=1.0.0
Provides-Extra: ai
Requires-Dist: crewai[anthropic,google-genai,litellm,openai]>=1.11.0; extra == 'ai'
Requires-Dist: google-genai>=0.2.0; extra == 'ai'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Provides-Extra: neo4j
Requires-Dist: neo4j>=5.0.0; extra == 'neo4j'
Description-Content-Type: text/markdown

<p align="center">
  <img src="logthread-logo.png" alt="LogThread" width="420" />
</p>

# LogThread

**Local-first code intelligence for developers and AI coding assistants.**

LogThread builds a live map of your codebase so you can understand how code, APIs, data, dependencies, changes, and runtime signals connect. It gives that context to both humans and MCP-compatible assistants, helping teams debug faster, make safer changes, and reduce AI guesswork.

---

## Why LogThread

Modern codebases are hard to reason about, especially when AI tools are generating or editing code. Teams run into the same problems over and over:

- functions get duplicated because existing code was missed
- imports and references point at the wrong modules
- changes ship without clear impact analysis
- dead code and hidden coupling accumulate over time
- logs, traces, and code live in different tools with no shared view

LogThread helps by turning the repository into a usable, navigable system model.

---

## What You Can Do

- Explore a graph of your codebase with files, symbols, APIs, tables, columns, dependencies, communities, and processes
- Trace entry points and request flows from API surface to downstream code and data
- Build agent-safe edit contracts so AI tools know what to change, where to change it, and what existing code to reuse
- Run change-risk and impact analysis before making edits or opening a PR
- Detect dead code and see why a symbol was classified as unused
- Query runtime logs from supported providers, cluster patterns locally, and correlate them back to code
- Serve the indexed codebase over MCP for Cursor, Claude, Windsurf, Cline, VS Code, and other compatible tools

---

## Quick Start

```bash
# Install
pip install logthread

# Index the current repository
cd /path/to/your/repo
logthread generate --full --name "my-service"

# Open the local UI
logthread ui
```

If you want to expose the repository to an MCP-compatible assistant:

```bash
logthread serve --watch --path /absolute/path/to/your/repo
```

For hosted AI helper features, install the optional extra:

```bash
pip install "logthread[ai]"
```

---

## Core Workflows

### 1. Understand a Codebase

Use the Explorer and Analysis workspaces to answer questions like:

- Where does this API go after the route handler?
- What tables and columns does this flow touch?
- What are the main entry points in this service?
- What code is likely unused?

### 2. Change Code More Safely

Use change analysis and edit contracts to answer:

- What breaks if I modify this symbol?
- Which files, tests, APIs, and data surfaces are affected?
- Where should an AI assistant edit code instead of creating duplicates?

### 3. Investigate Runtime Issues

Connect external log providers, fetch a bounded log slice, and analyze it locally to answer:

- What error patterns are showing up?
- Which requests or correlation IDs are involved?
- Which APIs, files, dependencies, and data entities are likely related?
- What looks like the likely root cause or first failing hop?

---

## Runtime Intelligence

LogThread can connect to external log systems and analyze the returned logs locally.

Current provider support includes:

- Grafana Loki
- Datadog Logs
- Splunk
- Sumo Logic

You can:

- configure connectors from the UI or CLI
- fetch logs for a provider-native query and time window
- auto-detect JSON and structured fields
- cluster repeated message patterns
- group events by trace, request, or correlation IDs
- visualize request journeys and runtime relationships
- correlate logs back to APIs, source files, dependencies, and database entities

Example CLI flow:

```bash
logthread logs connect \
  --name "Prod Loki" \
  --provider loki \
  --base-url https://loki.example.com \
  --bearer-token YOUR_TOKEN

logthread logs query <connector-id> '{service="api"} |= "error"' --hours 2 --limit 150
```

---

## MCP Setup

LogThread speaks the Model Context Protocol so AI assistants can consume indexed code intelligence directly.

Run the setup helper:

```bash
logthread setup
```

Or configure your client manually with the `logthread serve` command. Example:

```json
{
  "mcpServers": {
    "logthread": {
      "command": "logthread",
      "args": ["mcp", "--path", "/absolute/path/to/your/project"]
    }
  }
}
```

Restart your MCP client after updating its config.

---

## CLI Overview

```bash
logthread generate --full --name "my-service"   # Index a repository
logthread list                                  # Show indexed repositories
logthread ui                                    # Open the local UI
logthread serve --watch --path /repo            # Start MCP server for a repo
logthread status                                # Show index stats for the current repo
logthread context myFunction                    # Inspect symbol context
logthread impact myFunction --depth 4           # See downstream impact
logthread change-risk                           # Analyze the current git diff
logthread edit-contract "add retry logic"       # Build an agent-safe edit plan
logthread dead-code                             # List likely dead code
logthread doc --output architecture.md          # Generate architecture documentation
logthread export --output graph.html            # Export graph view
logthread logs list-connectors                  # List runtime log connectors
```

Run `logthread --help` for the full command set.

---

## Supported Languages

LogThread supports broad multi-language indexing, including:

Python, TypeScript, JavaScript, Go, Java, C#, Ruby, Rust, C, C++, PHP, Kotlin, Swift, Dart, Perl, and SQL.

The exact depth of analysis can vary by language and framework, but the goal is the same across the platform: build a useful, current map of the codebase and make it actionable in the UI, CLI, and MCP.

---

## Privacy and Deployment

LogThread is designed to be local-first.

- code indexing and graph analysis run locally
- the UI, MCP server, and change analysis run locally
- runtime log analysis runs locally after log data is fetched
- LogThread does not require a LogThread-hosted account to use the local product

Optional network access can still happen when you choose to use:

- external log providers such as Loki, Datadog, Splunk, or Sumo Logic
- optional hosted AI integrations
- opt-in external dependency intelligence sources

This makes it suitable for teams that want strong local control while still connecting approved provider systems when needed.
