agex-cli 0.11.0__py3-none-any.whl

agent_experience/commands/gamify/scripts/install.py

@@ -0,0 +1,196 @@
+import json
+from datetime import datetime, timezone
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+from agent_experience.core.backend import Backend
+from agent_experience.core.config import load as load_config
+from agent_experience.core.config import save as save_config
+from agent_experience.core.paths import ensure_init
+
+
+def _fragments_file() -> Traversable:
+    return files("agent_experience.commands.gamify").joinpath("assets", "hooks", "claude-code.json")
+
+
+def _fragments_for(backend: Backend) -> list[dict]:
+    if backend != Backend.CLAUDE_CODE:
+        return []
+    data = json.loads(_fragments_file().read_text(encoding="utf-8"))
+    return data["fragments"]
+
+
+def _hooks_file_for(backend: Backend, project_dir: Path) -> Path | None:
+    if backend == Backend.CLAUDE_CODE:
+        return project_dir / ".claude" / "hooks.json"
+    return None
+
+
+def _refuse(path: Path, reason: str) -> ValueError:
+    return ValueError(
+        f"{path} {reason}; refusing to overwrite. " "Fix or remove the file before re-running."
+    )
+
+
+def _load_hooks_file(path: Path) -> dict:
+    # Malformed or unexpectedly-shaped files are NEVER silently overwritten —
+    # the caller gets a ValueError, surfaces it as exit 2, and the user's file
+    # stays on disk untouched.
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise _refuse(path, f"is not valid JSON ({e})") from e
+    if not isinstance(data, dict):
+        raise _refuse(path, "is not a JSON object at the top level")
+    for entries in data.values():
+        if not isinstance(entries, list) or not all(isinstance(e, dict) for e in entries):
+            raise _refuse(path, "is not a mapping of event → list of hook objects")
+    return data
+
+
+def _write_hooks_file(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def _merge_fragments(hooks: dict, fragments: list[dict]) -> tuple[list[str], int]:
+    """Append each fragment's {id, hook} under its event if the id isn't already
+    there. Returns (all_fragment_ids_in_insertion_order, added_count)."""
+    written_ids: list[str] = []
+    added = 0
+    for frag in fragments:
+        event = frag["event"]
+        entry = {"id": frag["id"], "hook": frag["hook"]}
+        hooks.setdefault(event, [])
+        if not any(e.get("id") == frag["id"] for e in hooks[event]):
+            hooks[event].append(entry)
+            added += 1
+        written_ids.append(frag["id"])
+    return written_ids, added
+
+
+def _remove_ids_from_hooks(hooks: dict, ids_to_remove: set[str]) -> int:
+    """Filter entries matching ids_to_remove out of each event. Event keys whose
+    arrays become empty as a result of removal are deleted. Pre-existing empty
+    event arrays are left intact. Returns total entries removed."""
+    removed = 0
+    for event in list(hooks.keys()):
+        original = hooks[event]
+        filtered = [e for e in original if e.get("id") not in ids_to_remove]
+        event_removed = len(original) - len(filtered)
+        if event_removed == 0:
+            continue
+        removed += event_removed
+        if filtered:
+            hooks[event] = filtered
+        else:
+            del hooks[event]
+    return removed
+
+
+def install(backend: Backend) -> tuple[str, int, str]:
+    ensure_init()
+    project_dir = Path.cwd()
+    hooks_file = _hooks_file_for(backend, project_dir)
+    if hooks_file is None:
+        return (_unsupported_notice(backend), 0, "")
+
+    fragments = _fragments_for(backend)
+    if not fragments:
+        return (_unsupported_notice(backend), 0, "")
+
+    try:
+        hooks = _load_hooks_file(hooks_file)
+    except ValueError as e:
+        return ("", 2, f"agex: error: {e}")
+
+    written_ids, added_count = _merge_fragments(hooks, fragments)
+    if added_count:
+        _write_hooks_file(hooks_file, hooks)
+
+    cfg = load_config()
+    previous = cfg.installed.get("gamify", {})
+    if previous.get("hook_fragment_ids") != written_ids:
+        cfg.installed["gamify"] = {
+            "at": datetime.now(tz=timezone.utc).isoformat(),
+            "hook_fragment_ids": written_ids,
+        }
+        save_config(cfg)
+
+    rel = hooks_file.relative_to(project_dir)
+    if added_count:
+        status_line = (
+            f"- Added {added_count} hook fragment(s); "
+            f"ensured {len(written_ids)} present in `{rel}`."
+        )
+    else:
+        status_line = (
+            f"- Ensured {len(written_ids)} hook fragment(s) already present "
+            f"in `{rel}` (no changes)."
+        )
+    lines = [
+        f"# Gamify installed — {backend.value}",
+        "",
+        status_line,
+        "- Fragment IDs: " + ", ".join(f"`{i}`" for i in written_ids),
+        "",
+        f"Next: run `agex learn gamify --agent {backend.value}` to set up the levelup skill.",
+        "",
+    ]
+    return ("\n".join(lines), 0, "")
+
+
+def uninstall(backend: Backend) -> tuple[str, int, str]:
+    ensure_init()
+    project_dir = Path.cwd()
+    hooks_file = _hooks_file_for(backend, project_dir)
+    if hooks_file is None:
+        return (_unsupported_notice(backend), 0, "")
+
+    cfg = load_config()
+    installed = cfg.installed.get("gamify", {})
+    ids_to_remove = set(installed.get("hook_fragment_ids", []))
+    if not ids_to_remove:
+        return (f"# Gamify uninstalled — nothing to remove on {backend.value}.\n", 0, "")
+
+    rel = hooks_file.relative_to(project_dir)
+    # If the user already removed the hooks file, just drop the config record.
+    # Don't re-create the file with an empty object.
+    if not hooks_file.exists():
+        cfg.installed.pop("gamify", None)
+        save_config(cfg)
+        return (
+            f"# Gamify uninstalled — `{rel}` was already gone; " "cleared config record.\n",
+            0,
+            "",
+        )
+
+    try:
+        hooks = _load_hooks_file(hooks_file)
+    except ValueError as e:
+        return ("", 2, f"agex: error: {e}")
+
+    removed_count = _remove_ids_from_hooks(hooks, ids_to_remove)
+    if removed_count:
+        _write_hooks_file(hooks_file, hooks)
+
+    cfg.installed.pop("gamify", None)
+    save_config(cfg)
+
+    return (
+        f"# Gamify uninstalled — removed {removed_count} fragment(s) from `{rel}`.\n",
+        0,
+        "",
+    )
+
+
+def _unsupported_notice(backend: Backend) -> str:
+    return (
+        f"## `gamify` is not supported on {backend.value}\n\n"
+        f"Hooks are required to track usage events, and {backend.value} does not expose "
+        f"a hook interface agex can write to.\n\n"
+        "Want this supported? Open an issue: <https://github.com/OriNachum/agex/issues>\n"
+    )

agent_experience/commands/hook/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: hook
+description: Write and read agex tracking events.
+type: command
+---
+
+# `agex hook write <event> [key=value ...]` / `agex hook read --agent <backend>`
+
+## `write`
+
+Called by installed hooks (see `agex gamify`, Phase 7). Appends a JSON line to `.agex/data/<event>.json`. Silent. Safe for concurrent invocation (file locking via `portalocker`).
+
+```bash
+agex hook write post-tool-use tool=Read
+```
+
+## `read`
+
+Renders tracked events as a markdown table. Prints the source JSON path for deeper inspection.
+
+```bash
+agex hook read --agent claude-code
+```
+
+## Notes
+
+- Event names are free-form; conventional names: `post-tool-use`, `user-prompt`, `stop`, `sessions`.
+- Extra positional `key=value` pairs are captured into the payload. Empty keys (e.g., `=foo`) are dropped.
+- Timestamp (`ts`) is attached automatically; a positional `ts=<value>` overrides it (useful for replays).
+- The positional `<event>` name is authoritative — it always wins over any `event=...` pair in args.
+- Malformed JSON lines in `.agex/data/*.json` (e.g., from a partial write) are skipped with a warning on `hook read`, not raised.

agent_experience/commands/hook/assets/table.md.j2

@@ -0,0 +1,17 @@
+# Hook events — {{ backend }}
+
+**Source:** `{{ source }}`
+
+{% for stream in streams %}
+## `{{ stream.name }}` ({{ stream.events|length }})
+
+{% if stream.events -%}
+| ts | event | details |
+|---|---|---|
+{% for e in stream.events -%}
+| {{ e.ts }} | {{ stream.name }} | {{ e.details }} |
+{% endfor %}
+{%- else -%}
+_no events_
+{%- endif %}
+{% endfor %}

agent_experience/commands/hook/scripts/read.py

@@ -0,0 +1,38 @@
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+
+from agent_experience.core.backend import Backend
+from agent_experience.core.hook_io import load_events
+from agent_experience.core.paths import data_dir, ensure_init
+from agent_experience.core.render import render_string
+
+KNOWN_STREAMS = ["post-tool-use", "user-prompt", "stop", "sessions"]
+
+
+def _assets_root() -> Traversable:
+    # Anchor on the `commands` package (which has __init__.py) and navigate in.
+    # Avoids relying on namespace-package semantics for `assets/`, which is a
+    # data directory, not a package. Matches overview.py / learn.py pattern.
+    return files("agent_experience.commands").joinpath("hook", "assets")
+
+
+def run(backend: Backend) -> tuple[str, int, str]:
+    ensure_init()
+    streams = []
+    for name in KNOWN_STREAMS:
+        events = load_events(name)
+        summarized = [
+            {
+                "ts": e.get("ts", ""),
+                "details": ", ".join(f"{k}={v}" for k, v in e.items() if k not in ("ts", "event")),
+            }
+            for e in events
+        ]
+        streams.append({"name": name, "events": summarized})
+
+    template_text = _assets_root().joinpath("table.md.j2").read_text(encoding="utf-8")
+    out = render_string(
+        template_text,
+        {"backend": backend.value, "source": str(data_dir()), "streams": streams},
+    )
+    return (out, 0, "")

agent_experience/commands/hook/scripts/write.py

@@ -0,0 +1,24 @@
+from datetime import datetime, timezone
+
+from agent_experience.core.hook_io import append_event
+from agent_experience.core.paths import ensure_init
+
+
+def run(event: str, args: list[str]) -> tuple[str, int, str]:
+    ensure_init()
+    payload: dict = {"ts": datetime.now(tz=timezone.utc).isoformat()}
+    for arg in args:
+        if "=" in arg:
+            k, v = arg.split("=", 1)
+            if k:
+                payload[k] = v
+    # Positional event name is authoritative — it overrides any `event=...`
+    # pair in args so hook scripts can't misattribute events.
+    payload["event"] = event
+    try:
+        append_event(event, payload)
+    except ValueError as e:
+        # append_event → _stream_path rejects names that don't match the
+        # `^[a-z][a-z0-9-]*$` slug whitelist (path-traversal guard).
+        return ("", 2, f"agex: error: {e}")
+    return ("", 0, "")

agent_experience/commands/learn/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: learn
+description: Show available lessons, or teach one.
+type: command
+---
+
+# `agex learn [topic] --agent <backend>`
+
+Without a topic, lists the lessons available for your backend. With a topic, teaches it — emits a markdown lesson body plus inline skill-template code blocks you can write into your project.
+
+## From your shell tool
+
+```bash
+agex learn --agent claude-code
+agex learn introspect --agent claude-code
+```
+
+## Notes
+
+- Lessons gated on a backend feature (e.g., `gamify` needs hooks) may still appear in the list, but they are not currently annotated as unsupported in the menu — Phase 8 adds that capability-based routing.
+- v0.1 emits inline code blocks only. A future `--write` flag is tracked as an open issue.

agent_experience/commands/learn/assets/menu.md.j2

@@ -0,0 +1,7 @@
+# Lessons — {{ backend }}
+
+Run `agex learn <topic> --agent {{ backend }}` to learn one.
+
+{% for topic in topics -%}
+- **`{{ topic.name }}`** — {{ topic.description }}{% if topic.unsupported %} _(unsupported on {{ backend }}: {{ topic.unsupported }})_{% endif %}
+{% endfor %}

agent_experience/commands/learn/assets/topics/gamify/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: gamify
+description: Install usage tracking hooks and build a levelup skill to advise the user.
+type: lesson
+---
+
+# Lesson — set up gamification for {{ backend }}
+
+Two parts:
+
+## Part 1 — install the tracking hooks
+
+Run in your shell tool:
+
+```bash
+agex gamify --agent {{ backend }}
+```
+
+This writes backend-native hook fragments that call `agex hook write <event>` whenever you use a tool, submit a prompt, or stop. The events land in `.agex/data/`.
+
+To uninstall: `agex gamify --uninstall --agent {{ backend }}`.
+
+## Part 2 — build the `levelup` skill
+
+The hook data is inert without something to surface it. Build the levelup skill described in `agex learn levelup --agent {{ backend }}`, or copy its skill template directly:
+
+### `.claude/skills/levelup/SKILL.md`
+
+```markdown
+{{ skill_template_body }}
+```
+
+## After both parts
+
+Use your runtime normally for a few sessions. Then invoke `/levelup` — it will read the tracking data via `agex hook read` and advise the user.

agent_experience/commands/learn/assets/topics/gamify/assets/skill-template/claude-code/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: levelup
+description: Read agex usage tracking data and suggest a next-feature-to-learn for the user.
+type: command
+---
+
+# Level up
+
+> **Note:** Requires `agex hook read`, which ships in a future phase (Phase 6). Until it lands, this skill has no data source — treat it as a scaffold placeholder.
+
+Invoke when the user asks for what's next, or opportunistically after a long session.
+
+## Process
+
+1. Run in your shell tool: `agex hook read --agent claude-code`
+2. Count occurrences per event type.
+3. Pick **one** feature area the user is under-using (e.g., they have MCP servers configured but `post-tool-use` shows zero MCP tool calls).
+4. Suggest one concrete next step in 3-4 sentences.
+
+## Rule
+
+One suggestion per invocation. If nothing stands out, say so — don't invent.

agent_experience/commands/learn/assets/topics/introspect/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: introspect
+description: Build an agent-native introspect skill that audits your project setup and suggests next steps.
+type: lesson
+---
+
+# Lesson — build an `introspect` skill for {{ backend }}
+
+## What you'll end up with
+
+A backend-native skill (for {{ backend }}) that:
+1. Calls `agex overview --agent {{ backend }}` to read the project's current state.
+2. Identifies gaps (missing CLAUDE.md, no skills, no hooks, etc.).
+3. Suggests the next one or two improvements you could apply.
+4. Is small enough that invoking it doesn't blow your context budget.
+
+## Why build it instead of shipping it
+
+Two reasons: (1) each agent backend has its own native skill format, so no shipped skill fits perfectly; (2) you and the user stay in control of what gets installed into the project.
+
+## Step 1 — review the `agex overview` output
+
+Run `agex overview --agent {{ backend }}` now. Note which sections are empty — those are your candidate gaps.
+
+## Step 2 — create the skill file
+
+Write the file shown below to the path noted above its fence. Adjust the prose/tone to your project's voice.
+
+### `.claude/skills/introspect/SKILL.md`
+
+```markdown
+{{ skill_template_body }}
+```
+
+## Step 3 — try it
+
+Invoke `/introspect` (or equivalent) in your runtime. Read the output, apply one suggestion.
+
+## Why one suggestion at a time
+
+Agents that shove 10 recommendations into one turn overwhelm the user. The skill you just built is explicitly capped at two — if you want more later, iterate.

agent_experience/commands/learn/assets/topics/introspect/assets/skill-template/claude-code/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: introspect
+description: Audit the current project's agent setup and suggest 1-2 next improvements.
+type: command
+---
+
+# Introspect
+
+When the user asks to audit the agent setup, improve it, or "what should I add", invoke this skill.
+
+## Process
+
+1. Run in your shell tool: `agex overview --agent claude-code`
+2. Read the output. Count what exists under each section (skills, hooks, MCP, settings).
+3. Identify the two weakest sections — the ones most likely to unblock a real workflow next.
+4. Emit a short markdown reply: what's missing, why it matters, what adding it costs.
+
+## Rules
+
+- Cap suggestions at 2.
+- No "nice-to-haves." Only suggestions that unblock something concrete.
+- Don't install anything. Advise only.

agent_experience/commands/learn/assets/topics/levelup/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: levelup
+description: Build a skill that reads agex usage data and advises the user.
+type: lesson
+---
+
+# Lesson — build the `levelup` skill for {{ backend }}
+
+> **Preview:** This lesson depends on `agex gamify` (Phase 7) and `agex hook read` (Phase 6); neither is available in agex 0.3.0. Treat the steps below as a design preview — the emitted skill template won't have real data to read until those commands ship.
+
+Prerequisite: you've run `agex gamify --agent {{ backend }}` so there's data to read.
+
+## Step 1 — understand the data source
+
+Run `agex hook read --agent {{ backend }}` now. You'll see a JSON list of events (tool calls, prompts submitted, stops). The levelup skill will parse this and suggest one area for improvement.
+
+## Step 2 — create the skill file
+
+Write the file shown below to the path noted above its fence. This skill reads the tracking data and offers one concrete suggestion per invocation.
+
+### Skill template — `.claude/skills/levelup/SKILL.md`
+
+```markdown
+{{ skill_template_body }}
+```
+
+## Step 3 — try it after a few sessions
+
+Use your runtime normally for a few turns. Then invoke `/levelup` to see what the skill suggests.
+
+See also: `agex learn gamify --agent {{ backend }}` (bundles the full setup).

agent_experience/commands/learn/assets/topics/levelup/assets/skill-template/claude-code/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: levelup
+description: Read agex usage tracking data and suggest a next-feature-to-learn for the user.
+type: command
+---
+
+# Level up
+
+> **Note:** Requires `agex hook read`, which ships in a future phase (Phase 6). Until it lands, this skill has no data source — treat it as a scaffold placeholder.
+
+Invoke when the user asks for what's next, or opportunistically after a long session.
+
+## Process
+
+1. Run in your shell tool: `agex hook read --agent claude-code`
+2. Count occurrences per event type.
+3. Pick **one** feature area the user is under-using (e.g., they have MCP servers configured but `post-tool-use` shows zero MCP tool calls).
+4. Suggest one concrete next step in 3-4 sentences.
+
+## Rule
+
+One suggestion per invocation. If nothing stands out, say so — don't invent.

agent_experience/commands/learn/assets/topics/visualize/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: visualize
+description: Build a skill that renders a compact visual of your agent setup.
+type: lesson
+---
+
+# Lesson — build a `visualize` skill for {{ backend }}
+
+Same shape as introspect, but the output optimizes for *at-a-glance* rather than recommendations. The skill runs `agex overview --agent {{ backend }}`, compresses it into a tight markdown block (counts only, with a token target of < 500 output tokens), and echoes it for situational awareness.
+
+## Step 1 — understand the goal
+
+Run `agex overview --agent {{ backend }}` now. Note the counts of skills, hooks, MCP integrations, and CLAUDE.md status. The visualize skill will display these as a one-liner for quick reference.
+
+## Step 2 — create the skill file
+
+Write the file shown below to the path noted above its fence. This skill is intentionally minimal — no prose, no recommendations.
+
+### Skill template — `.claude/skills/visualize/SKILL.md`
+
+```markdown
+{{ skill_template_body }}
+```
+
+## Step 3 — invoke it
+
+Say "what do I have" or "show the setup" and invoke `/visualize` (or equivalent). You'll get a compact status bar.

agent_experience/commands/learn/assets/topics/visualize/assets/skill-template/claude-code/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: visualize
+description: At-a-glance snapshot of the project's agent setup — counts only, compact.
+type: command
+---
+
+# Visualize
+
+When the user says "what do I have", "show the setup", or similar.
+
+## Process
+
+1. `agex overview --agent claude-code`
+2. Emit a compact block: `Skills: N · Hooks: M · MCP: K · CLAUDE.md: ✓/✗`
+3. Stop. No recommendations, no prose paragraphs.
+
+## Rule
+
+Target < 500 output tokens. If you can't fit the summary, trim further.

agent_experience/commands/learn/scripts/learn.py

@@ -0,0 +1,72 @@
+import re
+from importlib.resources import as_file, files
+from importlib.resources.abc import Traversable
+
+from agent_experience.core.backend import Backend
+from agent_experience.core.render import render_string
+from agent_experience.core.skill_loader import Skill, load_skill
+
+_TOPIC_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+_SKILL_FILENAME = "SKILL.md"
+
+
+def _learn_assets() -> Traversable:
+    # Anchor on the `commands` package (which has __init__.py) and navigate in.
+    # Avoids relying on namespace-package semantics for `assets/`, which is a
+    # data directory, not a package. Matches explain.py / overview.py pattern.
+    return files("agent_experience.commands").joinpath("learn", "assets")
+
+
+def _load_skill_from_traversable(trav: Traversable) -> Skill:
+    # load_skill expects a pathlib.Path; resolve via as_file when needed.
+    with as_file(trav) as path:
+        return load_skill(path)
+
+
+def _list_topics() -> list[dict]:
+    topics: list[dict] = []
+    topics_root = _learn_assets().joinpath("topics")
+    for topic_dir in sorted(topics_root.iterdir(), key=lambda p: p.name):
+        if topic_dir.is_file():
+            continue
+        skill_md = topic_dir.joinpath(_SKILL_FILENAME)
+        if not skill_md.is_file():
+            continue
+        skill = _load_skill_from_traversable(skill_md)
+        # Use the directory name as the canonical slug — `run_topic` looks up
+        # by directory, so the menu's `agex learn <name>` invocation must
+        # match. Frontmatter `skill.name` is still available for drift checks.
+        topics.append(
+            {"name": topic_dir.name, "description": skill.description, "unsupported": None}
+        )
+    return topics
+
+
+def run_menu(backend: Backend) -> tuple[str, int, str]:
+    """Return (stdout, exit_code, stderr) for the topic menu."""
+    topics = _list_topics()
+    template_text = _learn_assets().joinpath("menu.md.j2").read_text(encoding="utf-8")
+    out = render_string(template_text, {"backend": backend.value, "topics": topics})
+    return (out, 0, "")
+
+
+def run_topic(topic: str, backend: Backend) -> tuple[str, int, str]:
+    """Return (stdout, exit_code, stderr) for a specific lesson topic."""
+    if not _TOPIC_RE.match(topic):
+        menu_out, _, _ = run_menu(backend)
+        return (menu_out, 2, f"agex: error: unknown topic '{topic}'")
+
+    topic_dir = _learn_assets().joinpath("topics", topic)
+    skill_md = topic_dir.joinpath(_SKILL_FILENAME)
+    if not skill_md.is_file():
+        menu_out, _, _ = run_menu(backend)
+        return (menu_out, 2, f"agex: error: unknown topic '{topic}'")
+
+    skill = _load_skill_from_traversable(skill_md)
+    template_path = topic_dir.joinpath("assets", "skill-template", backend.value, _SKILL_FILENAME)
+    template_body = template_path.read_text(encoding="utf-8") if template_path.is_file() else ""
+    rendered = render_string(
+        skill.body,
+        {"backend": backend.value, "skill_template_body": template_body},
+    )
+    return (rendered, 0, "")