{"id":50521964,"url":"https://github.com/thrillmade/logmind","last_synced_at":"2026-06-07T21:00:49.765Z","repository":{"id":358000192,"uuid":"1078395397","full_name":"thrillmade/logmind","owner":"thrillmade","description":"Branch-aware AI decision logging for development projects — AGENTS.md-canonical, link-integrity CI, skills.sh integration.","archived":false,"fork":false,"pushed_at":"2026-06-03T03:56:49.000Z","size":1528,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T05:25:35.625Z","etag":null,"topics":["agents-md","ai-agents","claude","cli","codex","cursor","decision-log","devtools","python","skdd","skill-driven-development"],"latest_commit_sha":null,"homepage":"https://logmind.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thrillmade.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-17T17:01:12.000Z","updated_at":"2026-06-02T18:10:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/thrillmade/logmind","commit_stats":null,"previous_names":["thrillmot/logmind","thrillmade/logmind"],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/thrillmade/logmind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrillmade%2Flogmind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrillmade%2Flogmind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrillmade%2Flogmind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrillmade%2Flogmind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thrillmade","download_url":"https://codeload.github.com/thrillmade/logmind/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrillmade%2Flogmind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34037777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents-md","ai-agents","claude","cli","codex","cursor","decision-log","devtools","python","skdd","skill-driven-development"],"created_at":"2026-06-03T05:00:56.266Z","updated_at":"2026-06-07T21:00:49.488Z","avatar_url":"https://github.com/thrillmade.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# logmind\n\n[![PyPI](https://img.shields.io/pypi/v/logmind.svg)](https://pypi.org/project/logmind/)\n[![Python versions](https://img.shields.io/pypi/pyversions/logmind.svg)](https://pypi.org/project/logmind/)\n[![CI](https://github.com/thrillmade/logmind/actions/workflows/test.yml/badge.svg)](https://github.com/thrillmade/logmind/actions/workflows/test.yml)\n[![skills.sh](https://www.skills.sh/b/thrillmade/agent-skills/logmind)](https://www.skills.sh/thrillmade/agent-skills/logmind)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nAI decision logging for development projects — branch-aware by default.\n\n## Why logmind\n\nCodebases lose the *why* behind their code faster than the *what*. logmind\ncaptures architectural and implementation decisions as you make them,\nattaches them to the relevant git branch, and surfaces them to the next\nhuman or AI that works in the repo. One CLI command per decision; the\npackage handles the docs, the branch routing, and the merge-time\naggregation.\n\n**Key concept:** Install once, init anywhere, log everything. Feature\nbranches get their own decision file; on PR merge a GitHub Action appends\na one-line summary to `docs/decisions.md` linking the PR + the branch\ndetail. AGENTS.md is the canonical agent-instruction file; per-tool files\n(CLAUDE.md, .cursorrules, ...) are 2-line stubs pointing to it.\n\n## Installation\n\n```bash\n# Using pipx (recommended)\npipx install logmind\n\n# Using Homebrew (macOS/Linux)\nbrew tap thrillmade/logmind\nbrew install logmind\n\n# Using pip\npip install logmind\n```\n\n## Required repo settings\n\n`logmind init` ships a GitHub Action (`regen-timeline.yml`) that VERIFIES\n`docs/timeline.md` is up to date on every PR — fail-fast if stale, no\nauto-commit. For the derived-file architecture to stay conflict-free\nbetween concurrent PRs, your repo needs:\n\n- **Strict required status checks on `main`** —\n  `Settings → Branches → Branch protection rule (or Ruleset)` →\n  *\"Require branches to be up to date before merging\"*. This forces a\n  PR to be rebased on latest `main` before merge, which is what makes\n  `docs/timeline.md` (and any other derived file) conflict-free across\n  concurrent PRs.\n\nWithout that toggle, two PRs in flight can both regenerate against\ndifferent base commits and merge-conflict on the derived file.\n\n### One-command setup via reporulez\n\nIf you'd rather not click through the GitHub UI, the\n[`clud-bug-logmind`](https://github.com/thrillmade/reporulez) variant of\n`reporulez` ships the canonical ruleset for repos using both logmind\nand clud-bug — strict status checks pinned to logmind's check names,\nrequired thread resolution, squash-only, the works:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/thrillmade/reporulez/main/bin/apply.sh \\\n  | bash -s -- owner/your-repo clud-bug-logmind\n```\n\n## Quick Start\n\n```bash\n# If installed via pipx/brew, it's already available globally\n\n# Initialize in your project\ncd your-project\nlogmind init\n\n# OR — install the full SkDD toolchain (logmind + clud-bug) in one go:\nlogmind init --with-skdd      # subprocesses to `npx clud-bug init` (requires Node 20+)\n\n# Log decisions - Python API\nfrom logmind import log\nlog(\"Chose FastAPI over Flask\",\n    reasoning=\"Need async/await for WebSocket handling\")\n\n# Or use CLI\nlogmind log \"Use PostgreSQL for database\" \\\n  -r \"Need ACID compliance\" \\\n  -a \"MongoDB\" -a \"SQLite\"\n\n# View and search decisions\nlogmind show\nlogmind search \"postgres\"\n\n# Log with a built-in template (pre-fills reasoning, alternatives, implications)\nlogmind log --template database \"Use PostgreSQL\"\nlogmind templates   # list all available templates\n\n# Analytics and stats\nlogmind stats\nlogmind stats --months 6\n\n# Aggregate decisions across multiple projects\nlogmind aggregate ~/projects/api ~/projects/frontend\nlogmind aggregate --summary ~/work/*/\n\n# Enforce decision logging with a pre-commit hook\nlogmind install-hook          # installs .git/hooks/pre-commit\nlogmind check-decisions       # run manually or in CI\n\n# Manage AI agents\nlogmind agents list\nlogmind agents add windsurf\n\n# View and modify configuration\nlogmind config list\nlogmind config get git.auto_push\nlogmind config set git.auto_push false\n\n# Upgrade logmind\nlogmind update\n\n# Auto-log with decorators\nfrom logmind import log_decision, log_choice\n\n@log_decision(\n    decision=\"Authenticate user with {method}\",\n    reasoning=\"Security checkpoint\"\n)\ndef authenticate(method=\"oauth\"):\n    # Your auth code\n    return True\n\n@log_choice(\n    choices={\n        \"redis\": \"Use Redis for caching\",\n        \"memory\": \"Use in-memory caching\",\n    }\n)\ndef select_cache():\n    return \"redis\" if is_production() else \"memory\"\n```\n\n## Contributing / Development Setup\n\nWorking on logmind itself? Set it up like any CLI tool:\n\n```bash\n# Clone the repo\ngit clone https://github.com/thrillmade/logmind.git\ncd logmind\n\n# Install globally in editable mode (like npm, git, docker)\npipx install -e .\n\n# Now just use it!\nlogmind log \"Add new feature\" -r \"Reasoning here\"\nlogmind show\nlogmind search \"keyword\"\n\n# Run tests\npython3 -m venv venv\nsource venv/bin/activate\npip install -e \".[dev]\"\npytest\n```\n\n**Why pipx?** logmind is a CLI tool, not a library. It should be globally available like `git` or `npm`.\n\n## Framework Integrations\n\n```python\n# LangChain — auto-log agent decisions (pip install logmind[langchain])\nfrom logmind.integrations import LangChainLogger\n\nchain = LLMChain(llm=llm, callbacks=[LangChainLogger()])\n\n# Custom framework — subclass BaseIntegration\nfrom logmind.integrations.base import BaseIntegration\n\nclass MyLogger(BaseIntegration):\n    def on_decision(self, output):\n        self.log(f\"Chose: {output}\", reasoning=\"My framework decided\")\n```\n\nSee [docs/custom-integrations.md](docs/custom-integrations.md) for patterns, examples, and publishing guide.\n\n## Documentation\n\n- **[Plan \u0026 Architecture](docs/plan.md)** - Vision, approach, and technical details\n- **[AI Agent Files](docs/ai-agent-files.md)** - How logmind integrates with AI instruction files\n- **[Custom Integrations](docs/custom-integrations.md)** - Build integrations for any AI framework\n- **[First Decision Example](docs/first-decision-example.md)** - What the initial decision looks like\n- **Development Status** - All phases complete ✅\n\n## How It Works\n\n1. **Install** logmind as a package\n2. **Init** creates `docs/` folder and inserts instructions into `CLAUDE.md` (preserving existing content)\n3. **Log** a decision - appends, archives old ones (keeps 20 recent), regenerates tree, commits, and pushes\n4. **Context** AI agents read the 20 most recent decisions and current file structure\n\n## Why logmind?\n\n- **Simple:** Two markdown files (recent + archive), no database\n- **Focused:** Only 20 most recent decisions for relevant AI context\n- **Git-native:** Every decision is a commit, git history is your audit trail\n- **AI-friendly:** Recent decisions + file structure = complete context\n- **Automatic:** Commits and pushes on every log\n\nSee [docs/plan.md](docs/plan.md) for complete architecture and roadmap.\n\n---\n\n## Part of the thrillmade SkDD toolchain\n\n[Skills-Driven Development](https://zakelfassi.com/skdd-skills-driven-development) (Zak Elfassi's methodology) gives you the loop; the thrillmade toolchain ships the parts:\n\n- **[logmind](https://github.com/thrillmade/logmind)** — the *why* behind every change (decision logging as commit primitive); skill-creation + testing + auditing\n- **[clud-bug](https://github.com/thrillmade/clud-bug)** — skill-driven PR review at gate time; every finding cites the skill that motivated it\n- **[agent-skills](https://github.com/thrillmade/agent-skills)** — public catalog of reusable skills\n- **[skills.sh](https://skills.sh)** — skill discovery + install\n\nEnd-to-end agentic auto dev: write skills first → log the *why* → run them against PRs → iterate based on usage. The tools work independently; better together.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthrillmade%2Flogmind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthrillmade%2Flogmind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthrillmade%2Flogmind/lists"}