logmind

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

# Using pipx (recommended)
pipx install logmind

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

# Using pip
pip install logmind

Required repo settings

logmind init ships GitHub Actions workflows that regenerate docs/timeline.md and docs/file-structure.md on every PR. For those to land cleanly, your repo needs:

1. Workflow write permissions — Settings → Actions → General → Workflow permissions = Read and write permissions. The regen workflow needs to push its commit back to the PR branch via GITHUB_TOKEN. Default on new repos may be read-only; flip it once.

2. Strict required status checks on main — Settings → Branches → Branch protection rule (or Ruleset) → "Require branches to be up to date before merging". This forces a PR to be rebased on latest main before merge, which is what makes the derived files (docs/timeline.md, docs/file-structure.md) conflict-free between concurrent PRs.

Without (1), the regen step fails to push and your docs/timeline.md stays stale. Without (2), two concurrent PRs editing docs/timeline.md can produce a merge conflict the bot can't resolve. Both settings are one-time toggles per repo.

Quick Start

# 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:

# 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

# 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 for patterns, examples, and publishing guide.

Documentation

• Plan & Architecture - Vision, approach, and technical details
• AI Agent Files - How logmind integrates with AI instruction files
• Custom Integrations - Build integrations for any AI framework
• First Decision Example - 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 for complete architecture and roadmap.