Metadata-Version: 2.4
Name: logmind
Version: 0.1.0
Summary: Decision logging for AI-assisted development - automatic tracking, git integration, and context for AI agents
Author: logmind contributors
License: MIT
Project-URL: Homepage, https://github.com/thrillmot/logmind
Project-URL: Documentation, https://github.com/thrillmot/logmind#readme
Project-URL: Repository, https://github.com/thrillmot/logmind
Project-URL: Bug Tracker, https://github.com/thrillmot/logmind/issues
Project-URL: Changelog, https://github.com/thrillmot/logmind/blob/main/CHANGELOG.md
Keywords: ai,decision-logging,documentation,development,llm,ai-agents,decision-tracking,git-integration,claude,gpt,copilot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Dynamic: license-file

# logmind

[![PyPI](https://img.shields.io/pypi/v/logmind.svg)](https://pypi.org/project/logmind/)
[![Python versions](https://img.shields.io/pypi/pyversions/logmind.svg)](https://pypi.org/project/logmind/)
[![CI](https://github.com/thrillmot/logmind/actions/workflows/test.yml/badge.svg)](https://github.com/thrillmot/logmind/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

AI decision logging for development projects — branch-aware by default.

## Why logmind

Codebases lose the *why* behind their code faster than the *what*. logmind
captures architectural and implementation decisions as you make them,
attaches them to the relevant git branch, and surfaces them to the next
human or AI that works in the repo. One CLI command per decision; the
package handles the docs, the branch routing, and the merge-time
aggregation.

**Key concept:** Install once, init anywhere, log everything. Feature
branches get their own decision file; on PR merge a GitHub Action appends
a one-line summary to `docs/decisions.md` linking the PR + the branch
detail. AGENTS.md is the canonical agent-instruction file; per-tool files
(CLAUDE.md, .cursorrules, ...) are 2-line stubs pointing to it.

## Installation

```bash
# Using pipx (recommended)
pipx install logmind

# Using Homebrew (macOS/Linux)
brew tap thrillmot/logmind
brew install logmind

# Using pip
pip install logmind
```

## Quick Start

```bash
# If installed via pipx/brew, it's already available globally

# Initialize in your project
cd your-project
logmind init

# Log decisions - Python API
from logmind import log
log("Chose FastAPI over Flask",
    reasoning="Need async/await for WebSocket handling")

# Or use CLI
logmind log "Use PostgreSQL for database" \
  -r "Need ACID compliance" \
  -a "MongoDB" -a "SQLite"

# View and search decisions
logmind show
logmind search "postgres"

# Log with a built-in template (pre-fills reasoning, alternatives, implications)
logmind log --template database "Use PostgreSQL"
logmind templates   # list all available templates

# Analytics and stats
logmind stats
logmind stats --months 6

# Aggregate decisions across multiple projects
logmind aggregate ~/projects/api ~/projects/frontend
logmind aggregate --summary ~/work/*/

# Enforce decision logging with a pre-commit hook
logmind install-hook          # installs .git/hooks/pre-commit
logmind check-decisions       # run manually or in CI

# Manage AI agents
logmind agents list
logmind agents add windsurf

# View and modify configuration
logmind config list
logmind config get git.auto_push
logmind config set git.auto_push false

# Upgrade logmind
logmind update

# Auto-log with decorators
from logmind import log_decision, log_choice

@log_decision(
    decision="Authenticate user with {method}",
    reasoning="Security checkpoint"
)
def authenticate(method="oauth"):
    # Your auth code
    return True

@log_choice(
    choices={
        "redis": "Use Redis for caching",
        "memory": "Use in-memory caching",
    }
)
def select_cache():
    return "redis" if is_production() else "memory"
```

## Contributing / Development Setup

Working on logmind itself? Set it up like any CLI tool:

```bash
# Clone the repo
git clone https://github.com/thrillmot/logmind.git
cd logmind

# Install globally in editable mode (like npm, git, docker)
pipx install -e .

# Now just use it!
logmind log "Add new feature" -r "Reasoning here"
logmind show
logmind search "keyword"

# Run tests
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pytest
```

**Why pipx?** logmind is a CLI tool, not a library. It should be globally available like `git` or `npm`.

## Framework Integrations

```python
# LangChain — auto-log agent decisions (pip install logmind[langchain])
from logmind.integrations import LangChainLogger

chain = LLMChain(llm=llm, callbacks=[LangChainLogger()])

# Custom framework — subclass BaseIntegration
from logmind.integrations.base import BaseIntegration

class MyLogger(BaseIntegration):
    def on_decision(self, output):
        self.log(f"Chose: {output}", reasoning="My framework decided")
```

See [docs/custom-integrations.md](docs/custom-integrations.md) for patterns, examples, and publishing guide.

## Documentation

- **[Plan & Architecture](docs/plan.md)** - Vision, approach, and technical details
- **[AI Agent Files](docs/ai-agent-files.md)** - How logmind integrates with AI instruction files
- **[Custom Integrations](docs/custom-integrations.md)** - Build integrations for any AI framework
- **[First Decision Example](docs/first-decision-example.md)** - What the initial decision looks like
- **Development Status** - All phases complete ✅

## How It Works

1. **Install** logmind as a package
2. **Init** creates `docs/` folder and inserts instructions into `CLAUDE.md` (preserving existing content)
3. **Log** a decision - appends, archives old ones (keeps 20 recent), regenerates tree, commits, and pushes
4. **Context** AI agents read the 20 most recent decisions and current file structure

## Why logmind?

- **Simple:** Two markdown files (recent + archive), no database
- **Focused:** Only 20 most recent decisions for relevant AI context
- **Git-native:** Every decision is a commit, git history is your audit trail
- **AI-friendly:** Recent decisions + file structure = complete context
- **Automatic:** Commits and pushes on every log

See [docs/plan.md](docs/plan.md) for complete architecture and roadmap.
