mordecai-coach 0.1.0

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

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. 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 CLI authenticated against your GitHub account, jq, and an Anthropic API key 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:

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

3. Configure your team's orgs and developers:

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

4. Run setup on each developer's machine:

   export MORDECAI_REPO_URL=[e-mail]: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:

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

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

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 Compound Engineering 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.

For security issues, see SECURITY.md.