codetalker-mcp 0.3.1__tar.gz

codetalker_mcp-0.3.1/.github/workflows/publish.yml

@@ -0,0 +1,70 @@
+name: publish
+
+# Publishes codetalker-mcp to PyPI when a vX.Y.Z tag is pushed.
+#
+# Gate: the wheel must pass the stranger-install smoke (fresh venv,
+# non-editable install, handshake, empty-home probe) before anything uploads.
+#
+# Auth: PyPI Trusted Publishing (OIDC) — no API tokens stored in the repo.
+# One-time prerequisite (repo owner): on pypi.org, under
+# project/codetalker-mcp/manage/publishing, register a pending publisher:
+#   owner=Ickleslimer  repo=codetalker  workflow=publish.yml
+#   environment=pypi
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Tag/version consistency guard
+        run: |
+          VERSION=$(grep -oP '(?<=__version__ = ")[^"]+' src/codetalker/__init__.py)
+          echo "__version__=$VERSION ref=$GITHUB_REF"
+          if [[ "$GITHUB_REF" == refs/tags/* ]]; then
+            TAG=${GITHUB_REF_NAME#v}
+            if [ "$TAG" != "$VERSION" ]; then
+              echo "::error::tag v$TAG does not match __version__ $VERSION"
+              exit 1
+            fi
+          fi
+
+      - name: Build sdist + wheel
+        run: uv build --out-dir dist
+
+      - name: Wheel smoke gate (fresh venv, non-editable install)
+        run: |
+          uv venv .smoke-venv --python 3.12
+          WHEEL=$(ls dist/*.whl)
+          uv pip install --python .smoke-venv/bin/python "$WHEEL"
+          .smoke-venv/bin/python scripts/stranger_smoke.py
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

codetalker_mcp-0.3.1/.github/workflows/stranger-smoke.yml

@@ -0,0 +1,45 @@
+name: stranger-smoke
+
+# Keeps the onboarding path honest: a fresh venv, a NON-EDITABLE install of
+# the checked-out tree (exactly what `pip install git+https://...` gives a
+# stranger, minus the network hop that would test the previous commit), a
+# full MCP handshake, and the empty-home probe.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  smoke:
+    name: stranger smoke (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Fresh venv + non-editable install (the stranger path)
+        shell: bash
+        run: |
+          uv venv .smoke-venv --python 3.12
+          # windows runners use Scripts/, posix use bin/ — test the file
+          PY=.smoke-venv/bin/python
+          if [ -f ".smoke-venv/Scripts/python.exe" ]; then
+            PY=.smoke-venv/Scripts/python.exe
+          fi
+          uv pip install --python "$PY" .
+          echo "SMOKE_PY=$PY" >> "$GITHUB_ENV"
+
+      - name: Run stranger smoke
+        shell: bash
+        run: |
+          "$SMOKE_PY" scripts/stranger_smoke.py

codetalker_mcp-0.3.1/.gitignore

@@ -0,0 +1,70 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+.smoke-venv/
+
+# Pytest / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# IDE & OS files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# CodeGraph local index (regenerable)
+.codegraph/
+
+# Local audit reports (may contain transcript excerpts)
+.audit/
+
+# Local audit helper scripts (not part of shipped tooling)
+scripts/analyze_audit_hits.py
+
+# Throwaway live-proof probe scripts (kept in .audit/, never shipped)
+live_probe*.py
+
+# Probe output dumps
+probe*.txt
+
+# Agent local instructions
+agents.md
+AGENTS.md
+*.local.md
+

codetalker_mcp-0.3.1/.python-version

@@ -0,0 +1 @@
+3.12

codetalker_mcp-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ickleslimer
+
+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.

codetalker_mcp-0.3.1/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.5
+Name: codetalker-mcp
+Version: 0.3.1
+Summary: Cross-harness agent conversation transcript normalizer and MCP server
+Project-URL: Homepage, https://github.com/Ickleslimer/codetalker
+Project-URL: Repository, https://github.com/Ickleslimer/codetalker
+Project-URL: Issues, https://github.com/Ickleslimer/codetalker/issues
+Project-URL: Changelog, https://github.com/Ickleslimer/codetalker/releases
+Author: Ickleslimer
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,claude,codex,context-recovery,cursor,llm,mcp,transcripts
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: click>=8.4.2
+Requires-Dist: mcp>=2.0.0
+Requires-Dist: pydantic>=2.13.4
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
+Requires-Dist: pytest>=9.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CodeTalker
+
+> Cross-harness agent conversation transcript normalizer and MCP server.
+
+CodeTalker is an agent-callable tool and MCP server that normalizes conversation transcripts from different AI coding harnesses into a unified schema. This allows any agent to pick up context, search past decisions, or read thread history without requiring manual handoff documents.
+
+---
+
+> [!IMPORTANT]
+> **Privacy: read-only, local-only, no telemetry.**
+> CodeTalker **reads** your agent harnesses' local conversation history and nothing else.
+> - **Read-only by construction.** Every harness database it touches (Cursor, Freebuff, OpenCode, Windsurf/Devin) is opened in SQLite read-only mode (`?mode=ro`) — the driver itself refuses writes, so a bug in CodeTalker cannot modify your sessions. It writes no config files, keeps no cache, stores no state of its own.
+> - **What it touches.** Only the harnesses' own storage directories listed in the [support table below](#supported-harnesses--verification-status) (e.g. `~/.codex/sessions`, `~/.config/freebuff-desktop`, `%APPDATA%/Cursor`), plus local OpenCode desktop logs to discover that app's local server port. Nothing on your machine is modified.
+> - **Nothing is sent anywhere.** The server speaks stdio only — it talks exclusively to the agent harness that launched it, on your machine. There is no telemetry, no analytics, no update checks. The one network-shaped exception is disclosed: the OpenCode sidecar adapter may issue a **local** HTTP GET to your own running OpenCode desktop app (port discovered from that app's local logs) to read session messages. No transcript data ever leaves your machine via CodeTalker — it leaves only if the agent harness you use sends tool results to its own model backend, which is outside CodeTalker's control.
+
+---
+
+## Capabilities & Schema
+
+- **Normalized Intermediate Format**: Standardized `TextBlock`, `ThinkingBlock`, `ToolCallBlock`, `ToolResultBlock`, `CodeDiffBlock`, `AttachmentBlock`, `ApprovalBlock`, `SystemEventBlock`.
+- **DAG / Branch Aware**: Multi-branch threads (e.g. in ChatGPT/Codex or Claude Code) are exposed as distinct threads sharing a conversation ID.
+- **Fast Metadata Discovery**: Fast header peeking and recency sorting for collections with 500+ session files.
+
+---
+
+## Supported Harnesses & Verification Status
+
+| Harness | Aliases | Storage Locations | Test Status | Notes |
+|---|---|---|---|---|
+| **OpenAI Codex CLI** | `codex`, `chatgpt` | `~/.codex/sessions/**/rollout-*.jsonl`, `session_index.jsonl` | **Live Verified** | Tested across 480+ local CLI sessions with trailing timestamps and DAG resolution. |
+| **OpenAI ChatGPT Desktop** | `chatgpt` | `%LOCALAPPDATA%/Packages/OpenAI.ChatGPT-Desktop_*/.../IndexedDB` | **Live Verified** | Tested via `ccl-chromium-reader` LevelDB parser. *(See fragility disclaimer below)*. |
+| **ChatGPT Export DAG** | `chatgpt` | `conversations.json` (Export Archive) | **Live Verified** | Linearizes branching conversation DAG trees into distinct threads. |
+| **Devin (formerly Windsurf)** | `devin`, `windsurf` | `~/.codeium/chat_state/*.pb`, `state.vscdb` | **Live Verified** | Pure-Python wire-level Protobuf stream parser and workspace SQLite reader. |
+| **Freebuff** | `freebuff`, `codebuff` | `~/.config/freebuff-desktop/projects/*/desktop-v2.db` | **Live Verified** | Full multi-turn conversation logs, reasoning traces, image attachments, and tool calls. |
+| **OpenCode Desktop** | `opencode`, `open_code` | `%APPDATA%/ai.opencode.desktop/drafts.sqlite` | **Live Verified** | Decodes workspace paths, models, prompt histories, and active session drafts. *(See notes below)*. |
+| **Google Antigravity** | `antigravity`, `agy` | `~/.gemini/antigravity/brain/*/transcript.jsonl` | **Live Verified** | Real-time transcript logs, XML cleanup, subagent trees, thinking blocks, and checkpoints. |
+| **Cursor IDE** | `cursor` | `%APPDATA%/Cursor/User/globalStorage/state.vscdb` | **Live Verified** | Scans `composerHeaders` across 50+ workspaces, bubbles, diffs, and reasoning traces. |
+| **Claude Code CLI** | `claude`, `claudecode` | `~/.claude/projects/*/sessions/*.jsonl` | **Fixture Tested (YMMV)** | Implemented against Anthropic Messages API specs; not verified against an active local installation. |
+| **Aider Pair Programmer** | `aider` | `.aider.chat.history.md`, `~/.aider.chat.history.md` | **Fixture Tested (YMMV)** | Implemented for markdown chat logs and `<<<< SEARCH ... === ... >>>>` diffs; not installed locally. |
+| **GitHub Copilot Chat** | `copilot`, `github_copilot` | `%APPDATA%/Code/User/workspaceStorage/*/chatSessions/*.jsonl` | **Fixture Tested (YMMV)** | Implemented for VSCode chat session JSONL logs; not verified against an active local installation. |
+
+---
+
+## Stability, Fragility & Compatibility Disclaimers
+
+> [!WARNING]
+> **ChatGPT Desktop App (LevelDB Cache) Fragility**
+> The ChatGPT Desktop application uses Chromium IndexedDB / LevelDB to cache conversation state locally. This storage engine is unversioned, undocumented, and frequently modified by OpenAI between app updates.
+> - **Recommendation**: For reliable long-term retrieval, prefer **Codex CLI rollouts** (`~/.codex/sessions`) or the official data export (`conversations.json`).
+
+> [!NOTE]
+> **OpenCode Desktop Cloud Streaming vs Local Drafts**
+> OpenCode Desktop persists active drafts, models (`grok`, `gpt-5.6`, `x-preview`), and user prompt history in `%APPDATA%/ai.opencode.desktop/drafts.sqlite`. Because multi-turn assistant completions are rendered via live server-side WebSockets, local desktop records represent client-side prompts and active workspace drafts. Full multi-turn assistant outputs and tool executions are available if using **OpenCode CLI** JSONL logs (`~/.opencode/sessions/*.jsonl`).
+
+> [!IMPORTANT]
+> **Cursor SQLite Schema Evolution**
+> Cursor's internal storage schema in `state.vscdb` (`composerHeaders`, `cursorDiskKV`, `composerData`, `bubbleId`) evolves across Cursor releases. CodeTalker connects in read-only mode (`?mode=ro`) with schema fallbacks, but major upstream Cursor redesigns may require updating field mappings.
+
+> [!TIP]
+> **Fixture-Tested Adapters (YMMV)**
+> The adapters for **Claude Code CLI**, **Aider**, and **GitHub Copilot Chat** have complete normalization logic verified by unit test fixtures, but have not been live-tested against active local installations on this machine. If you use these tools and encounter non-standard directory structures or version variations, use the `root_path` parameter to point CodeTalker directly to your transcript folder.
+
+---
+
+## MCP Tools
+
+| Tool | Parameters | Description |
+|---|---|---|
+| `codetalk_capabilities` | _(none)_ | List harnesses, aliases, ID guidance, context-recovery playbook, and recommended read defaults. Call once per agent session. |
+| `codetalk_list` | `harness`, `conversation_id`, `working_directory`, `since`, `limit`, `root_path`, `include_capabilities`, `include_harness_status` | List sessions (slim by default). Filter by `working_directory` for project-scoped recovery. |
+| `codetalk_resolve_session` | `working_directory`, `harness`, `display_name`, `root_path`, `limit` | Resolve the most recent session for a project path when `session_id` is unknown (common Freebuff context-loss recovery). Optional `display_name` narrows by thread title. |
+| `codetalk_read` | `session_id`, `harness`, `working_directory`, `since`, `until`, `since_last_user_input`, `conversation_only`, `exclude_actor_roles`, `include_thinking`, `include_raw_data`, `max_step_chars`, `offset`, `from_end`, `limit`, `root_path` | Read normalized steps. Provide `session_id` **or** `working_directory`. Defaults: tail slice (`from_end=true`), conversation-only (`conversation_only=true`), no raw payloads (`include_raw_data=false`). |
+| `codetalk_branches` | `conversation_id`, `harness`, `root_path` | DAG branch tree, fork points, and subagent hierarchy (`branch_id` usually equals `session_id`). |
+| `codetalk_diff_branches` | `conversation_id`, `branch_a`, `branch_b`, `harness`, `summary_only`, `include_raw_data`, `limit_per_branch`, `from_end`, `root_path` | Compare branches. Defaults to `summary_only=true` (counts/metadata only). |
+| `codetalk_filter` | `session_id`, `harness`, `working_directory`, `keywords`, `step_types`, `actor_roles`, `conversation_only`, `exclude_actor_roles`, `since_last_user_input`, `include_thinking`, `include_raw_data`, `max_step_chars`, `offset`, `from_end`, `limit`, `root_path` | Filter steps by keywords, types, or roles. Accepts `session_id` or `working_directory`. |
+| `codetalk_search` | `query`, `harness`, `working_directory`, `since`, `limit`, `max_sessions_to_search`, `search_scope`, `root_path` | Search titles and transcript content. Pass `working_directory` or `harness` when scoped to one project. Title hits use `match_type=title`. |
+| `codetalk_info` | `session_id`, `harness`, `working_directory`, `root_path` | Fast metadata without step bodies (refreshes step counts when possible). Accepts `session_id` or `working_directory`. |
+
+### Agent quickstart
+
+1. `codetalk_capabilities` — learn harness names, aliases, tool catalog, and unsupported hallucinated names (`read_transcript`, etc.).
+2. **Decision tree:**
+   - Lost context + know project path → `codetalk_resolve_session` → `codetalk_read(since_last_user_input=true)`
+   - Know `session_id` → `codetalk_read`
+   - Grep / find by title → `codetalk_search(query=..., working_directory=... or harness=...)`
+   - Branch history → `codetalk_branches` / `codetalk_diff_branches`
+3. `codetalk_list` — browse metadata; filter with `working_directory` and/or `harness` on busy machines.
+4. `codetalk_read` with defaults — tail slice without system injections or `raw_data`.
+
+Note: Codex CLI rollouts appear under harness `chatgpt`; use `session_id` for reads and `conversation_id` for branch tools.
+
+### Per-harness MCP onboarding
+
+| Harness | Setup notes |
+|---|---|
+| **Cursor / Antigravity / Claude Desktop** | Add MCP block with `uv run --project /path/to/codetalker codetalker`. Restart after config changes. |
+| **Freebuff** | Config in `~/.config/freebuff-desktop`. Approve the MCP consent sidecar when prompted, then restart. Verify with `codetalk_capabilities`. |
+| **Codex desktop** | MCP config differs from CLI; mirror a working Cursor/Antigravity definition if supported. Desktop may not expose MCP. |
+| **OpenCode** | Desktop drafts are prompt-only; use CLI JSONL or `codetalk_search(query='<thread title>')` for cross-harness title lookup. |
+
+`codetalk_capabilities` and `codetalk_info` return `server.project_root` — update MCP config if it points at a stale scratch copy.
+
+### Context recovery (Freebuff-first)
+
+Some harnesses lose **in-flight prompt context** while the **full transcript remains on disk**. Freebuff is the most common case: the agent may reply with *"I can't see the session context…"* even though `desktop-v2.db` still has every turn.
+
+**Symptom → fix**
+
+1. User says *continue* but the Freebuff agent is blind.
+2. Call `codetalk_resolve_session(working_directory="<project path>", harness="freebuff")` to get the latest `session_id` for that repo.
+3. Call `codetalk_read(working_directory="<project path>", harness="freebuff", since_last_user_input=true)` — or pass the resolved `session_id` — to recover what the user last asked and what the agent already did.
+4. Optionally `codetalk_search(query="can't see the session context", harness="freebuff")` to find other threads that hit the same failure.
+
+`working_directory` accepts plain paths (`C:/path/to/myproject`) or `file://` URIs. Matching is normalized and case-insensitive on Windows. You do **not** need `session_id` when you know the project path — `codetalk_read` and `codetalk_info` accept `working_directory` directly.
+
+Cross-harness recovery works too: open any harness with CodeTalker MCP configured (e.g. Cursor), point it at the Freebuff `working_directory`, and read the persisted transcript from there.
+
+`codetalk_capabilities` returns the full recovery playbook in `context_recovery`.
+
+#### v0.3: trigger-gated recovery + continue tokens
+
+Since v0.3 the recovery mandate is **trigger-gated and per-client**:
+
+- **Per-client instructions.** The handshake tailors `instructions` to the connecting client (via `clientInfo.name`): harnesses with known mid-thread context loss (Freebuff) receive the full marker-gated mandate; every other harness receives a short fallback. Healthy turns on any harness do **zero** recovery work.
+- **Mechanical wipe markers.** Restart/failed-turn notices (`<since_your_last_turn>`, `<failed_turn>`, session-ended system notices) are detected in the transcript tail — no model judgment required for the loud class of wipes.
+- **Continue tokens.** `codetalk_recover` now returns a `continue_token` line (`codetalker-v3-continue {…}`): an integrity-signed anchor (session, working directory, last user turn, transcript length). Agents end substantive turns with it; a later wiped turn passes it back as `claimed_token`, and the server verifies the agent's memory against the transcript on disk — anchors that were silently dropped or edited fail verification. `codetalk_recover_token` is the verification-only form. Silent mid-session wipes leave no transcript artifact, so their detection stays with the antecedent check — the token makes the recovery **verifiable** instead of guessed.
+- **Freebuff consent sidecar.** `codetalk_recover_token` is new, so Freebuff requires a one-time tool re-approval in the Freebuff UI (remove and re-add the codetalker server) before the tool is callable there.
+
+---
+
+## Installation & Setup
+
+### Install from PyPI
+
+Published as **`codetalker-mcp`** (the name `codetalker` on PyPI belongs to an
+unrelated 2014 package):
+
+```bash
+pip install codetalker-mcp
+# or
+uv tool install codetalker-mcp
+```
+
+MCP config entries then need no repo path:
+
+```json
+{
+  "mcpServers": {
+    "codetalker": {
+      "command": "uvx",
+      "args": ["--from", "codetalker-mcp", "codetalker"]
+    }
+  }
+}
+```
+
+> [!NOTE]
+> **ChatGPT Desktop adapter dependency.** The ChatGPT Desktop (IndexedDB/LevelDB)
+> adapter relies on `ccl-chromium-reader`, which is **only available from GitHub**
+> (it has no PyPI package, so it cannot be a pip dependency). Every other adapter
+> works out of the box. To enable ChatGPT Desktop support:
+>
+> ```bash
+> pip install "git+https://github.com/cclgroupltd/ccl_chromium_reader.git"
+> ```
+>
+> Without it, that one adapter reports `registered: false` / fails gracefully;
+> Codex CLI rollouts (harness `codex`/`chatgpt`) are unaffected.
+
+### Running locally (development)
+```bash
+uv sync
+uv run pytest -v
+uv run codetalker --log-level INFO
+```
+
+### Propagating MCP config after a move or clone
+
+When the repo moves (e.g. to `D:/codetalker`), every harness MCP entry must point at the new path. Run the installer from the repo root:
+
+```powershell
+.\scripts\install-harnesses.ps1 -ProjectRoot D:\codetalker
+```
+
+What it updates (when those config files exist on your machine):
+
+| Harness | Config file |
+|---|---|
+| **Cursor** | `%USERPROFILE%\.cursor\mcp.json` |
+| **Codex** | `%USERPROFILE%\.codex\config.toml` (`[mcp_servers.codetalker]`) |
+| **Antigravity** | `%USERPROFILE%\.gemini\antigravity\mcp_config.json` |
+| **Claude Desktop** | `%APPDATA%\Claude\claude_desktop_config.json` |
+
+Each file is backed up to `*.bak` before overwrite. **Freebuff** is not patched automatically — remove and re-add codetalker in the Freebuff client UI so a fresh MCP approval is minted (see script output for suggested command/args).
+
+Optional path-independent mode (installs a global `codetalker` shim via uv):
+
+```powershell
+.\scripts\install-harnesses.ps1 -UseUvTool
+```
+
+Limit to specific harnesses: `-Harness Cursor,Codex`. Preview changes: `-WhatIf`.
+
+After running, restart each harness and call `codetalk_capabilities` — confirm `server.project_root` matches your install.
+
+### Cross-platform installer (macOS / Linux / any OS)
+
+The same wiring logic ships as a stdlib-only Python entry point — usable immediately
+after `pip install git+https://github.com/Ickleslimer/codetalker.git`, no PowerShell
+required:
+
+```bash
+# preview what would change (default; modifies nothing)
+codetalker-install --project-root /path/to/codetalker
+
+# apply
+codetalker-install --project-root /path/to/codetalker --write
+
+# uv tool users (after: uv tool install /path/to/codetalker)
+codetalker-install --uv-tool --write
+```
+
+Targets are the same as the PowerShell script (Cursor, Antigravity, Claude Desktop,
+Codex TOML); existing `codetalker` entries are replaced in place, other MCP servers
+are preserved, every modified file gets a one-shot `.bak` backup, and CRLF line
+endings survive on Windows-written configs. The Claude Desktop config resolves to
+`%APPDATA%\Claude\claude_desktop_config.json` on Windows and
+`~/.claude/claude_desktop_config.json` elsewhere. Freebuff stays manual on every
+platform (client-managed consent sidecar). On Windows, either installer works; the
+PowerShell variant additionally offers `uv tool install` integration.
+
+### Adding to MCP Configuration (manual)
+
+In your agent harness MCP config (e.g., Antigravity, Claude Desktop, Cursor):
+
+```json
+{
+  "mcpServers": {
+    "codetalker": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--project",
+        "/path/to/codetalker",
+        "codetalker"
+      ]
+    }
+  }
+}
+```
+
+### Development: the stranger-install smoke
+
+CI (`.github/workflows/stranger-smoke.yml`) keeps the onboarding path honest on
+every push/PR: on ubuntu, macos, and windows runners it creates a **fresh venv**,
+installs the checked-out tree **non-editable** (exactly what
+`pip install git+https://github.com/Ickleslimer/codetalker.git` gives a stranger —
+CI deliberately installs from the tree rather than the GitHub URL, which would test
+the *previous* commit on push events), then runs `scripts/stranger_smoke.py`:
+
+- stdio handshake + full tool catalog (core 8 tools present)
+- v0.3 per-client instruction tailoring (freebuff mandate vs. short fallback)
+- `codetalk_capabilities` answers, and its version matches the installed dist
+- **empty-home probe**: with `HOME`/`USERPROFILE`/`APPDATA`/`XDG_*` redirected to
+  an empty temp dir, capabilities and list answer gracefully (`count: 0`)
+
+Run the same check locally against your editable install (skips the fresh-venv
+step but exercises the identical assertions):
+
+```bash
+uv pip install . && python scripts/stranger_smoke.py
+```
+
+Or replicate CI exactly:
+
+```bash
+uv venv .smoke-venv --python 3.12
+uv pip install --python .smoke-venv/Scripts/python.exe .   # bin/python on posix
+.smoke-venv/Scripts/python.exe scripts/stranger_smoke.py
+```