codex-coach 0.1.0

package/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codex-coach"
+version = "0.1.0"
+description = "Local-first Codex usage coach and plugin"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Codex Coach Contributors" }]
+keywords = ["codex", "ai", "developer-tools", "analytics", "prompting"]
+dependencies = []
+
+[project.scripts]
+codex-coach = "codex_coach.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codex_coach"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/assets",
+  "/src",
+  "/skills",
+  "/.codex-plugin",
+  "/README.md",
+  "/install.sh",
+  "/install.ps1",
+]

package/skills/codex-coach/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: codex-coach
+description: Use when the user asks to analyze their Codex usage, habits, prompt quality, model/effort choices, tool usage, project switching, context recovery, or wants suggestions for Codex custom instructions or AGENTS.md improvements.
+---
+
+# Codex Coach
+
+Codex Coach is a local-first coaching workflow. Use the bundled `codex-coach` command for deterministic parsing; do not manually scan large logs unless the command is unavailable.
+
+## Quick Workflow
+
+1. Run a health check:
+
+```sh
+codex-coach doctor
+```
+
+2. Generate or refresh the report:
+
+```sh
+codex-coach report --since 7d
+```
+
+3. Use beginner or expert mode based on the user:
+
+```sh
+codex-coach report --since 7d --mode beginner
+codex-coach report --since 7d --mode expert
+```
+
+4. Read `~/.codex-coach/reports/latest.md` and summarize the highest-impact findings.
+
+5. For config improvements, generate review files:
+
+```sh
+codex-coach suggest-config --since 7d
+```
+
+6. For a prompt the user is drafting, lint it directly:
+
+```sh
+codex-coach lint-prompt "fix the login bug"
+```
+
+7. Explain that suggestions are reviewable and are not applied automatically.
+
+## User Modes
+
+- Beginner: summarize the top 3 findings in plain language, then give one habit to try this week.
+- Expert: include model/effort mix, tool mix, verification ratio, compactions, project capsules, and skill opportunities.
+- Project-specific: if the user names a project path, filter your discussion to that project from the report/facts if present.
+
+## What To Surface
+
+- Project capsules: explain the likely workflow, top friction, and suggested local instruction.
+- Prompt rewrites: show the redacted preview and the safer template, not the raw original prompt.
+- Confidence: keep low-confidence suggestions tentative; high-confidence suggestions can be presented as the next best habit.
+- Skill opportunities: if the report flags a repeated workflow, suggest a small user skill with trigger, context to gather, verification commands, and resume rules.
+
+## Guardrails
+
+- Keep reports local. Do not upload logs.
+- Do not paste full prompt bodies or source code into chat.
+- Treat `~/.codex-coach/facts/latest.json` as the machine-readable source of truth.
+- Do not edit global custom instructions or `AGENTS.md` automatically; show the generated suggestion file and ask for explicit approval before applying any change.
+
+## Optional References
+
+- Read `references/prompt-rubric.md` when explaining prompt quality scores.
+- Read `references/config-suggestions.md` when discussing custom instruction or AGENTS.md changes.
+- Read `references/privacy.md` when the user asks what data is read or stored.

package/skills/codex-coach/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Codex Coach"
+  short_description: "Analyze local Codex habits and usage."
+  brand_color: "#22C55E"
+  default_prompt: "Use $codex-coach to analyze my Codex usage this week."
+
+policy:
+  allow_implicit_invocation: true

package/skills/codex-coach/references/config-suggestions.md

@@ -0,0 +1,35 @@
+# Config Suggestion Policy
+
+Codex Coach can suggest changes to global custom instructions, user-level skills, or project `AGENTS.md` files. Suggestions must be reviewable and reversible.
+
+Recommended suggestion format:
+
+- Evidence: one metric or repeated pattern from the report.
+- Confidence: low, medium, or high.
+- Change: the exact instruction text to add.
+- Benefit: what should improve.
+- Rollback: how to remove it if it does not help.
+
+Common suggestions:
+
+```md
+When a task is simple, local, or status-oriented, default to medium reasoning. Reserve high or xhigh for ambiguous debugging, architecture, security, broad refactors, or unclear failures.
+```
+
+```md
+Before saying a fix is complete, run the smallest meaningful verification command or inspect the live/runtime state when applicable.
+```
+
+```md
+For long tasks, keep a short durable checklist or artifact ledger so work can resume safely after compaction or interruption.
+```
+
+```md
+For multi-project work, prefer short project capsules over one large global instruction.
+```
+
+For repeated workflows, prefer a user skill over a long global instruction:
+
+```md
+When this workflow appears, gather [project context], follow [steps], verify with [commands], and resume from [ledger/checklist] after interruption.
+```

package/skills/codex-coach/references/privacy.md

@@ -0,0 +1,25 @@
+# Privacy Model
+
+Codex Coach is local-first.
+
+Default inputs:
+
+- `~/.codex/sessions/**/*.jsonl`
+- `~/.codex/archived_sessions/*.jsonl`
+- Optional Codex config and project metadata only when a user asks for deeper recommendations.
+
+Default outputs:
+
+- `~/.codex-coach/facts/latest.json`
+- `~/.codex-coach/reports/latest.md`
+- `~/.codex-coach/reports/weekly-YYYY-MM-DD.md`
+- `~/.codex-coach/suggestions/*.patch.md`
+
+Default redaction:
+
+- Full prompts are not written to Markdown reports.
+- Source code is not included.
+- File paths, URLs, emails, secret-like tokens, and long opaque strings are replaced in previews.
+- Prompt rewrites are generated as generic templates and do not include raw private details.
+- Project capsules use redacted project labels instead of full local paths.
+- Config suggestions are written as review files and are not applied automatically.

package/skills/codex-coach/references/prompt-rubric.md

@@ -0,0 +1,21 @@
+# Prompt Quality Rubric
+
+Codex Coach scores prompts from 0 to 10 using local text only.
+
+- Excellent: clear action plus enough context, or a brief reply that is unambiguous because the previous Codex turn asked for a choice.
+- Good: actionable but missing one optional detail.
+- Needs work: too short to identify the target, missing the failing symptom, or using vague words like "fix", "run", "delete", or "make better" without context.
+
+Do not treat brevity as bad by itself. Brief prompts like "yes", "proceed", "run tests", or "commit" can be high quality when Codex has enough local context.
+
+When recommending improvements, prefer templates:
+
+```text
+[action] in [project/file] because [symptom]. Success means [observable result].
+```
+
+```text
+Debug [error text]. I expected [expected behavior], but got [actual behavior].
+```
+
+`codex-coach lint-prompt "..."` applies the same rubric to a single draft prompt. If the score is low, present the suggested rewrite as a template, not as a claim that Codex Coach knows the missing private details.

package/src/codex_coach/__init__.py

@@ -0,0 +1,3 @@
+"""Local-first Codex usage coach."""
+
+__version__ = "0.1.0"

package/src/codex_coach/cli.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .install import install_from_source, uninstall
+from .parser import iter_log_paths, scan_logs
+from .paths import default_paths
+from .prompts import score_prompt
+from .reports import render_markdown_report, write_json_facts, write_markdown_report, write_suggestion_files
+from .timeutil import parse_since
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="codex-coach", description="Local-first Codex usage coach")
+    parser.add_argument("--home", help="Override HOME for testing or portable installs")
+    parser.add_argument("--codex-home", help="Override Codex home directory")
+    parser.add_argument("--coach-home", help="Override Codex Coach output directory")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("doctor", help="Check local Codex Coach setup")
+
+    scan = sub.add_parser("scan", help="Scan Codex logs and write JSON facts")
+    scan.add_argument("--since", default="7d", help="Window such as 7d, 2w, 24h, or ISO timestamp")
+
+    report = sub.add_parser("report", help="Write a Markdown coaching report")
+    report.add_argument("--since", default="7d")
+    report.add_argument("--mode", choices=("beginner", "expert"), default="beginner")
+    report.add_argument("--expert", action="store_true", help="Include raw expert metrics")
+
+    suggest = sub.add_parser("suggest-config", help="Write reviewable config suggestion files")
+    suggest.add_argument("--since", default="7d")
+
+    lint = sub.add_parser("lint-prompt", help="Score one prompt and suggest a safer rewrite")
+    lint.add_argument("prompt", nargs="*", help="Prompt text. Reads stdin when omitted.")
+    lint.add_argument("--json", action="store_true", help="Write machine-readable JSON")
+
+    install_cmd = sub.add_parser("install", help="Install command, plugin, skill, and default config")
+    install_cmd.add_argument("--source-root", default=_repo_root(), help="Source checkout root")
+    install_cmd.add_argument("--schedule", choices=("daily", "weekly", "none"), default="weekly")
+
+    sub.add_parser("uninstall", help="Remove installed command, plugin, skill, and scheduler files")
+
+    args = parser.parse_args(argv)
+    paths = default_paths(home=args.home, codex_home=args.codex_home, coach_home=args.coach_home)
+
+    try:
+        if args.command == "doctor":
+            return _doctor(paths)
+        if args.command == "scan":
+            facts = _scan(paths, args.since)
+            print(f"Wrote facts to {paths.facts_dir / 'latest.json'}")
+            return 0
+        if args.command == "report":
+            facts = _scan(paths, args.since)
+            generated_at = datetime.now(UTC)
+            report_text = render_markdown_report(facts, generated_at=generated_at, expert=args.expert, mode=args.mode)
+            latest, weekly = write_markdown_report(report_text, paths.reports_dir, generated_at=generated_at)
+            print(f"Wrote report to {latest}")
+            print(f"Wrote weekly copy to {weekly}")
+            return 0
+        if args.command == "suggest-config":
+            facts = _scan(paths, args.since)
+            written = write_suggestion_files(facts, paths.suggestions_dir)
+            for path in written:
+                print(f"Wrote suggestion {path}")
+            return 0
+        if args.command == "lint-prompt":
+            prompt_text = " ".join(args.prompt).strip() if args.prompt else sys.stdin.read().strip()
+            return _lint_prompt(prompt_text, as_json=args.json)
+        if args.command == "install":
+            result = install_from_source(Path(args.source_root), paths, schedule=args.schedule)
+            for key, value in result.items():
+                print(f"{key}: {value}")
+            return 0
+        if args.command == "uninstall":
+            removed = uninstall(paths)
+            if removed:
+                for path in removed:
+                    print(f"Removed {path}")
+            else:
+                print("Nothing to remove")
+            return 0
+    except Exception as exc:  # noqa: BLE001 - CLI should provide a direct error.
+        print(f"codex-coach: {exc}", file=sys.stderr)
+        return 1
+    return 1
+
+
+def _scan(paths, since: str) -> dict:
+    since_dt = parse_since(since)
+    paths.ensure_output_dirs()
+    facts = scan_logs(paths.codex_home, since_dt=since_dt, since_label=since)
+    facts["generated_at"] = datetime.now(UTC).isoformat(timespec="seconds")
+    write_json_facts(facts, paths.facts_dir / "latest.json")
+    return facts
+
+
+def _doctor(paths) -> int:
+    log_paths = iter_log_paths(paths.codex_home)
+    print(f"home: {paths.home}")
+    print(f"codex_home: {paths.codex_home} {'OK' if paths.codex_home.exists() else 'MISSING'}")
+    print(f"coach_home: {paths.coach_home}")
+    print(f"log_files: {len(log_paths)}")
+    print(f"reports_dir: {paths.reports_dir}")
+    command = paths.home / ".local" / "bin" / "codex-coach"
+    print(f"command: {command} {'OK' if command.exists() else 'not installed'}")
+    plugin = paths.home / "plugins" / "codex-coach" / ".codex-plugin" / "plugin.json"
+    print(f"plugin: {plugin} {'OK' if plugin.exists() else 'not installed'}")
+    skill = paths.home / ".agents" / "skills" / "codex-coach" / "SKILL.md"
+    print(f"skill: {skill} {'OK' if skill.exists() else 'not installed'}")
+    return 0 if paths.codex_home.exists() else 1
+
+
+def _lint_prompt(prompt_text: str, *, as_json: bool) -> int:
+    score = score_prompt(prompt_text)
+    result = {
+        "score": score.score,
+        "category": score.category,
+        "reason": score.reason,
+        "missing": list(score.missing),
+        "preview": score.preview,
+        "rewrite": score.rewrite,
+    }
+    if as_json:
+        print(json.dumps(result, indent=2, sort_keys=True))
+        return 0 if score.category != "needs_work" else 2
+
+    print(f"Score: {score.score}/10 ({score.category})")
+    print(f"Reason: {score.reason}")
+    if score.missing:
+        print(f"Missing: {', '.join(score.missing)}")
+    print(f"Preview: {score.preview}")
+    print(f"Try: {score.rewrite}")
+    return 0 if score.category != "needs_work" else 2
+
+
+def _repo_root() -> str:
+    return str(Path(__file__).resolve().parents[2])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/codex_coach/install.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+from .paths import CoachPaths
+
+PLUGIN_NAME = "codex-coach"
+
+
+def install_from_source(source_root: Path, paths: CoachPaths, *, schedule: str = "weekly") -> dict[str, str]:
+    source_root = source_root.resolve()
+    paths.ensure_output_dirs()
+    paths.coach_home.mkdir(parents=True, exist_ok=True)
+    _write_default_config(paths, schedule=schedule)
+    _copy_app(source_root, paths.app_dir)
+    _install_command(paths)
+    plugin_path = _install_plugin(source_root, paths.home)
+    skill_paths = _install_user_skills(source_root, paths.home)
+    marketplace = _update_marketplace(paths.home, plugin_path)
+    scheduler = _write_scheduler(paths, schedule=schedule)
+    return {
+        "coach_home": str(paths.coach_home),
+        "command": str(paths.home / ".local" / "bin" / "codex-coach"),
+        "plugin": str(plugin_path),
+        "skills": ", ".join(str(path) for path in skill_paths),
+        "marketplace": str(marketplace),
+        "scheduler": str(scheduler) if scheduler else "not configured",
+    }
+
+
+def uninstall(paths: CoachPaths) -> list[str]:
+    removed: list[str] = []
+    command = paths.home / ".local" / "bin" / "codex-coach"
+    if command.exists():
+        command.unlink()
+        removed.append(str(command))
+    for target in (
+        paths.home / "plugins" / PLUGIN_NAME,
+        paths.home / ".agents" / "skills" / PLUGIN_NAME,
+        paths.home / ".codex" / "skills" / PLUGIN_NAME,
+    ):
+        if target.exists():
+            shutil.rmtree(target)
+            removed.append(str(target))
+    _remove_marketplace_entry(paths.home)
+    for target in _scheduler_paths(paths):
+        if target.exists():
+            target.unlink()
+            removed.append(str(target))
+    return removed
+
+
+def _copy_app(source_root: Path, app_dir: Path) -> None:
+    if app_dir.exists():
+        shutil.rmtree(app_dir)
+    ignore = shutil.ignore_patterns(".git", ".venv", "__pycache__", ".pytest_cache", "dist", "build", "*.egg-info")
+    shutil.copytree(source_root, app_dir, ignore=ignore)
+
+
+def _install_command(paths: CoachPaths) -> None:
+    bin_dir = paths.home / ".local" / "bin"
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    command = bin_dir / "codex-coach"
+    python = os.environ.get("PYTHON", "python3")
+    command.write_text(
+        "#!/usr/bin/env sh\n"
+        "set -eu\n"
+        f'PYTHONPATH="{paths.app_dir / "src"}${{PYTHONPATH:+:$PYTHONPATH}}" exec {python} -m codex_coach.cli "$@"\n',
+        encoding="utf-8",
+    )
+    command.chmod(0o755)
+
+
+def _install_plugin(source_root: Path, home: Path) -> Path:
+    plugin_root = home / "plugins" / PLUGIN_NAME
+    if plugin_root.exists():
+        shutil.rmtree(plugin_root)
+    plugin_root.mkdir(parents=True, exist_ok=True)
+    for name in (".codex-plugin", "skills", "README.md", "LICENSE"):
+        source = source_root / name
+        target = plugin_root / name
+        if source.is_dir():
+            shutil.copytree(source, target)
+        elif source.exists():
+            shutil.copy2(source, target)
+    return plugin_root
+
+
+def _install_user_skills(source_root: Path, home: Path) -> list[Path]:
+    skill_source = source_root / "skills" / PLUGIN_NAME
+    targets = [
+        home / ".agents" / "skills" / PLUGIN_NAME,
+        home / ".codex" / "skills" / PLUGIN_NAME,
+    ]
+    installed: list[Path] = []
+    for target in targets:
+        if target.exists():
+            shutil.rmtree(target)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(skill_source, target)
+        installed.append(target)
+    return installed
+
+
+def _update_marketplace(home: Path, plugin_path: Path) -> Path:
+    marketplace = home / ".agents" / "plugins" / "marketplace.json"
+    marketplace.parent.mkdir(parents=True, exist_ok=True)
+    if marketplace.exists():
+        try:
+            data = json.loads(marketplace.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            data = _new_marketplace()
+    else:
+        data = _new_marketplace()
+    plugins = [item for item in data.get("plugins", []) if item.get("name") != PLUGIN_NAME]
+    plugins.append(
+        {
+            "name": PLUGIN_NAME,
+            "source": {"source": "local", "path": "./plugins/codex-coach"},
+            "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
+            "category": "Productivity",
+        }
+    )
+    data["plugins"] = plugins
+    marketplace.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return marketplace
+
+
+def _remove_marketplace_entry(home: Path) -> None:
+    marketplace = home / ".agents" / "plugins" / "marketplace.json"
+    if not marketplace.exists():
+        return
+    try:
+        data = json.loads(marketplace.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return
+    data["plugins"] = [item for item in data.get("plugins", []) if item.get("name") != PLUGIN_NAME]
+    marketplace.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def _new_marketplace() -> dict:
+    return {"name": "personal", "interface": {"displayName": "Personal"}, "plugins": []}
+
+
+def _write_default_config(paths: CoachPaths, *, schedule: str) -> None:
+    if paths.config_file.exists():
+        return
+    paths.config_file.write_text(
+        "\n".join(
+            [
+                "# Codex Coach config",
+                "redact_prompts = true",
+                "include_source_code = false",
+                f'schedule = "{schedule}"',
+                'default_since = "7d"',
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+
+def _write_scheduler(paths: CoachPaths, *, schedule: str) -> Path | None:
+    if schedule == "none":
+        return None
+    if schedule not in {"daily", "weekly"}:
+        raise ValueError(f"unsupported schedule: {schedule}")
+    systemd_dir = paths.home / ".config" / "systemd" / "user"
+    if os.name == "posix" and Path("/run/systemd").exists():
+        systemd_dir.mkdir(parents=True, exist_ok=True)
+        service = systemd_dir / "codex-coach.service"
+        timer = systemd_dir / "codex-coach.timer"
+        service.write_text(
+            "[Unit]\nDescription=Codex Coach report\n\n"
+            "[Service]\nType=oneshot\n"
+            f"ExecStart={paths.home / '.local' / 'bin' / 'codex-coach'} report --since 7d\n",
+            encoding="utf-8",
+        )
+        calendar = "09:00" if schedule == "daily" else "Sun 09:00"
+        timer.write_text(
+            f"[Unit]\nDescription=Run Codex Coach {schedule}\n\n"
+            f"[Timer]\nOnCalendar={calendar}\nPersistent=true\n\n"
+            "[Install]\nWantedBy=timers.target\n",
+            encoding="utf-8",
+        )
+        return timer
+
+    launch_agents = paths.home / "Library" / "LaunchAgents"
+    if os.name == "posix" and (paths.home / "Library").exists():
+        launch_agents.mkdir(parents=True, exist_ok=True)
+        plist = launch_agents / f"com.codex-coach.{schedule}.plist"
+        interval = (
+            "<dict><key>Hour</key><integer>9</integer></dict>"
+            if schedule == "daily"
+            else "<dict><key>Weekday</key><integer>0</integer><key>Hour</key><integer>9</integer></dict>"
+        )
+        plist.write_text(
+            f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>com.codex-coach.{schedule}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>{paths.home / '.local' / 'bin' / 'codex-coach'}</string>
+    <string>report</string>
+    <string>--since</string>
+    <string>7d</string>
+  </array>
+  <key>StartCalendarInterval</key>
+  {interval}
+</dict>
+</plist>
+""",
+            encoding="utf-8",
+        )
+        return plist
+    return None
+
+
+def _scheduler_paths(paths: CoachPaths) -> list[Path]:
+    return [
+        paths.home / ".config" / "systemd" / "user" / "codex-coach.service",
+        paths.home / ".config" / "systemd" / "user" / "codex-coach.timer",
+        paths.home / "Library" / "LaunchAgents" / "com.codex-coach.weekly.plist",
+        paths.home / "Library" / "LaunchAgents" / "com.codex-coach.daily.plist",
+    ]