Metadata-Version: 2.4
Name: mordecai-coach
Version: 0.1.0
Summary: Capture, learn, and redistribute lessons from your team's AI coding sessions.
Project-URL: Homepage, https://github.com/aysen-info/mordecai
Project-URL: Repository, https://github.com/aysen-info/mordecai
Project-URL: Issues, https://github.com/aysen-info/mordecai/issues
Author: Aysen
License: MIT License
        
        Copyright (c) 2026 Aysen
        
        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.
License-File: LICENSE
Keywords: agentic-coding,claude-code,compound-engineering,developer-tools,lessons-learned
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: anthropic<1,>=0.49
Requires-Dist: pyyaml<7,>=6.0
Provides-Extra: dev
Requires-Dist: pytest-mock<4,>=3.14; extra == 'dev'
Requires-Dist: pytest<9,>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Mordecai Coach

**Capture, learn, and redistribute lessons from your team's AI coding sessions.**

Mordecai Coach is a continuous learning loop for teams using [Claude Code](https://claude.com/claude-code). It watches each developer's sessions, redacts secrets, extracts patterns, and re-injects those lessons into every future session — so the same mistake doesn't get made twice across the team.

> Last verified working: 2026-04-24 (Python 3.11+, macOS, Claude Code).

---

## Why this exists

Every Claude Code session contains real signal: a developer corrects a bad fix, the model learns a quirk in the codebase, a teammate's review surfaces a pattern. When the session ends, that signal evaporates. The next session — even with the same developer on the same problem — starts cold.

Mordecai Coach turns each session into a small contribution to a shared corpus of "instincts" — short, specific lessons in the form *when X happens, do Y, because Z*. The corpus compounds. The next time any developer on the team hits a similar situation, the relevant instincts are already loaded into Claude Code's context as `@`-imported guidance.

The mechanics:

- A `SessionEnd` hook stages each transcript locally.
- A launchd daemon redacts secrets from the transcript and pushes it to a private repo.
- A daily GitHub Actions workflow extracts new instincts from the previous day's sessions and activity.
- The daemon pulls those instincts back to every developer's machine and rewrites their `.claude/coach-lessons.md` so they're auto-loaded into the next session.

---

## Architecture

```
Developer Machine                              GitHub (your private repo)
┌──────────────────────────┐                   ┌──────────────────────────────┐
│ SessionEnd hook           │  push sessions   │ sessions/{user}/{proj}/...   │
│ → ~/.mordecai/staging      │─────────────────▶│ activity/{user}/{date}.md    │
│                           │                   │                              │
│ launchd daemon             │                   │ ┌──────────────────────────┐ │
│ (every 5 min)              │  pull lessons    │ │ Daily GH Actions:        │ │
│ → ~/.mordecai/repo         │◀─────────────────│ │ extract → dedupe → write │ │
│ → .claude/coach-lessons.md│                   │ │ lessons/{user}/instincts │ │
└──────────────────────────┘                   │ └──────────────────────────┘ │
                                                └──────────────────────────────┘
```

The four pipelines:

| Pipeline | Where it runs | What it does |
|---|---|---|
| **Capture** | Each developer's machine | `SessionEnd` hook writes the transcript to `~/.mordecai/staging/`, filtered to only repos in tracked orgs. |
| **Redact** | Each developer's machine | Daemon strips secrets (AWS, GitHub, Anthropic, OpenAI, SendGrid tokens, bearer tokens, DB URLs, private keys) before any commit. Fails closed — if redaction fails, the transcript stays in staging. |
| **Extract** | GitHub Actions, daily | Reads the previous day's sessions and GitHub activity, calls the Claude API, produces structured instincts as YAML files. |
| **Redistribute** | Each developer's machine | Daemon pulls the latest instincts and rewrites `~/Projects/.claude/coach-lessons.md` so Claude Code auto-loads them via `@`-import. |

---

## Quickstart

> **Prerequisites:** macOS, Python 3.11+, [`gh`](https://cli.github.com/) CLI authenticated against your GitHub account, [`jq`](https://stedolan.github.io/jq/), and an [Anthropic API key](https://console.anthropic.com/) for the daily pipeline.

1. **Fork or create your team's repo.** This is where redacted sessions and the lesson corpus will live. Recommended: private. The repo URL is what each developer's daemon clones from.

2. **Clone and install:**

   ```bash
   git clone https://github.com/aysen-info/mordecai.git
   cd mordecai
   pip install -r requirements.txt
   ```

3. **Configure your team's orgs and developers:**

   ```bash
   cp config.yaml.example config.yaml
   # edit config.yaml — set tracked_orgs and tracked_developers
   ```

4. **Run setup on each developer's machine:**

   ```bash
   export MORDECAI_REPO_URL=git@github.com:your-team/your-fork.git
   python3 scripts/setup.py
   ```

   This installs the `SessionEnd` hook, clones the shared repo into `~/.mordecai/repo/`, and loads the launchd daemon.

5. **Enable the daily pipeline.** In GitHub Actions, add `ANTHROPIC_API_KEY` as a repo secret, then enable the `daily-pipeline.yml` workflow. By default it ships in `workflow_dispatch`-only mode — you trigger it manually until you're comfortable with the cost profile, then uncomment the `cron:` schedule.

That's it. After the first daily run, each developer's `.claude/coach-lessons.md` will start populating, and Claude Code will auto-load it via the `@`-import you set up in your project's `CLAUDE.md`.

---

## Configuration

`config.yaml` is gitignored — every team has their own copy. The example file documents each field. The minimum:

```yaml
tracked_orgs:
  - your-org

tracked_developers:
  - alice
  - bob
```

Additional knobs (Anthropic model selection, custom redaction patterns, repo URL for daily summary links) are documented in `config.yaml.example`.

The launchd daemon runs every 5 minutes. The daily pipeline runs on whatever schedule you set in `daily-pipeline.yml`.

---

## Honest limitations

Mordecai Coach is a working tool, but it's deliberately scoped — read this section before you adopt it.

- **macOS only.** The session-capture daemon uses launchd. Linux and Windows aren't supported and aren't on the roadmap.
- **Claude Code only.** The session JSONL format and the `@`-import mechanism are Claude Code-specific. Other agents (Codex, Gemini CLI, Cursor) aren't integrated.
- **Anthropic API costs are real.** A team of 4–6 developers running the daily pipeline typically spends a few dollars per day on extraction. The default ships with `workflow_dispatch`-only so you can profile costs before enabling the schedule. Set a budget alarm in your Anthropic console either way.
- **Showcase project.** This repo is shared as a working example of the pattern; it isn't actively staffed. Issues and PRs may receive slow replies. If you fork it, you own the fork.
- **No guarantee secrets are caught.** The redaction patterns cover common cases (AWS, GitHub, Anthropic, OpenAI, SendGrid, bearer tokens, DB URLs, private keys, generic env-var assignments) and fail closed on errors, but novel secret formats may slip through. Review the redaction patterns and add custom ones for any team-specific identifiers.

---

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Audit the working tree for any internal references before pushing
bash scripts/audit-internal-refs.sh --strict
```

The codebase is small (~10 modules, ~300 tests). The four pipelines are independent — each can be run in isolation:

```bash
python -m mordecai_coach.redact <input.jsonl> <output.jsonl>
python -m mordecai_coach.analyze --date 2026-04-23
python -m mordecai_coach.effectiveness --date 2026-04-23
python -m mordecai_coach.generate_coach_lessons
```

---

## Credits

Mordecai Coach is built on top of the [Every's](https://every.to/guides/compound-engineering) [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin) ecosystem — the `ce-*` skills and agents that ship with Claude Code framework. None of those skills are vendored into this repo; they're external dependencies the project was developed with. They are also highly recommended.

The instinct format and the broader "compound your team's knowledge" framing are drawn from that ecosystem. If you're new to the pattern, the `ce-brainstorm`, `ce-plan`, `ce-work`, and the all-important `ce-compound` skills are a good starting point.

---

## License

MIT — see [LICENSE](LICENSE).

For security issues, see [SECURITY.md](SECURITY.md).
