agex-cli 0.11.0__py3-none-any.whl

agent_experience/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("agex-cli")

agent_experience/__main__.py

@@ -0,0 +1,4 @@
+from agent_experience.cli import _main_entrypoint
+
+if __name__ == "__main__":
+    _main_entrypoint()

agent_experience/backends/acp/probe.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+from agent_experience.backends.claude_code.probe import ProbeResult
+
+
+def probe(project_dir: Path) -> ProbeResult:
+    """Stub ACP probe — v0.1 returns empty. Full discovery tracked as open issue."""
+    del project_dir  # accepted for signature parity with other probes; real discovery deferred
+    return ProbeResult()

agent_experience/backends/capabilities/acp.yaml

@@ -0,0 +1,7 @@
+hooks: false
+hooks_alternative: |
+  ACP-speaking agents (KiroCLI, OpenCode) do not currently expose hooks.
+  Track usage via the ACP transport layer or a shell wrapper.
+mcp: true
+skills: false
+agents: false

agent_experience/backends/capabilities/claude-code.yaml

@@ -0,0 +1,4 @@
+hooks: true
+mcp: true
+skills: true
+agents: true

agent_experience/backends/capabilities/codex.yaml

@@ -0,0 +1,7 @@
+hooks: false
+hooks_alternative: |
+  Codex does not expose a hook interface. Wrap your Codex invocation in a shell
+  script that calls `agex hook write` before/after each turn as a workaround.
+mcp: true
+skills: false
+agents: false

agent_experience/backends/capabilities/copilot.yaml

@@ -0,0 +1,7 @@
+hooks: false
+hooks_alternative: |
+  GitHub Copilot CLI does not expose a hook interface in v0.1-era versions.
+  Track usage via a shell wrapper that calls `agex hook write`.
+mcp: false
+skills: false
+agents: false

agent_experience/backends/claude_code/probe.py

@@ -0,0 +1,97 @@
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from agent_experience.core.skill_loader import load_skill
+
+_CLAUDE_DIR = ".claude"
+
+
+@dataclass
+class ProbeResult:
+    skills: list[dict[str, Any]] = field(default_factory=list)
+    hooks: list[dict[str, Any]] = field(default_factory=list)
+    agents: list[dict[str, Any]] = field(default_factory=list)
+    mcp_servers: list[dict[str, Any]] = field(default_factory=list)
+    claude_md: Path | None = None
+    settings: dict[str, Any] | None = None
+    warnings: list[str] = field(default_factory=list)
+
+
+def _read_skill(path: Path) -> tuple[dict[str, Any] | None, str | None]:
+    try:
+        skill = load_skill(path)
+    except (ValueError, OSError, yaml.YAMLError) as e:
+        return None, str(e)
+    return (
+        {
+            "name": skill.name,
+            "description": skill.description,
+            "path": str(path),
+        },
+        None,
+    )
+
+
+def _probe_settings(claude_dir: Path, result: ProbeResult) -> None:
+    settings = claude_dir / "settings.json"
+    if not settings.exists():
+        return
+    try:
+        result.settings = json.loads(settings.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        result.warnings.append(f"could not parse {settings}: {e}")
+
+
+def _probe_skills(claude_dir: Path, result: ProbeResult) -> None:
+    skills_dir = claude_dir / "skills"
+    if not skills_dir.is_dir():
+        return
+    # Sort for deterministic snapshot ordering across platforms / filesystems.
+    for skill_md in sorted(skills_dir.glob("*/SKILL.md")):
+        parsed, err = _read_skill(skill_md)
+        if parsed is not None:
+            result.skills.append(parsed)
+        else:
+            result.warnings.append(f"could not parse {skill_md}: {err}")
+
+
+def _probe_hooks(claude_dir: Path, result: ProbeResult) -> None:
+    hooks_file = claude_dir / "hooks.json"
+    if not hooks_file.exists():
+        return
+    try:
+        data = json.loads(hooks_file.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        result.warnings.append(f"could not parse {hooks_file}: {e}")
+        return
+    if not isinstance(data, dict):
+        result.warnings.append(f"could not parse {hooks_file}: expected a JSON object")
+        return
+    for event, entries in data.items():
+        if not isinstance(entries, list):
+            result.warnings.append(
+                f"could not parse {hooks_file}: expected list for event '{event}'"
+            )
+            continue
+        result.hooks.append({"event": event, "entries": entries})
+
+
+def probe(project_dir: Path) -> ProbeResult:
+    result = ProbeResult()
+    if not project_dir.exists():
+        return result
+
+    claude_md = project_dir / "CLAUDE.md"
+    if claude_md.exists():
+        result.claude_md = claude_md
+
+    claude_dir = project_dir / _CLAUDE_DIR
+    _probe_settings(claude_dir, result)
+    _probe_skills(claude_dir, result)
+    _probe_hooks(claude_dir, result)
+
+    return result

agent_experience/backends/codex/probe.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+
+from agent_experience.backends.claude_code.probe import ProbeResult
+
+
+def probe(project_dir: Path) -> ProbeResult:
+    """Minimal Codex probe — reads AGENTS.md if present. Other discovery deferred."""
+    result = ProbeResult()
+    if not project_dir.exists():
+        return result
+    agents_md = project_dir / "AGENTS.md"
+    if agents_md.exists():
+        result.claude_md = (
+            agents_md  # reusing field — rename to `project_memory` in a future cleanup
+        )
+    return result

agent_experience/backends/copilot/probe.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+from agent_experience.backends.claude_code.probe import ProbeResult
+
+
+def probe(project_dir: Path) -> ProbeResult:
+    """Stub Copilot probe — v0.1 returns empty. Full discovery tracked as open issue."""
+    del project_dir  # accepted for signature parity with other probes; real discovery deferred
+    return ProbeResult()

agent_experience/cli.py

@@ -0,0 +1,170 @@
+import sys
+from typing import Any, Optional
+
+import typer
+
+from agent_experience import __version__
+from agent_experience.commands.explain.scripts import explain as explain_script
+from agent_experience.commands.gamify.scripts import install as gamify_script
+from agent_experience.commands.hook.scripts import read as hook_read_script
+from agent_experience.commands.hook.scripts import write as hook_write_script
+from agent_experience.commands.learn.scripts import learn as learn_script
+from agent_experience.commands.overview.scripts import overview as overview_script
+from agent_experience.core.backend import parse_backend
+
+app = typer.Typer(
+    name="agex",
+    help="Agent-operated developer-experience CLI.",
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Optional[bool] = typer.Option(
+        None, "--version", callback=_version_callback, is_eager=True
+    ),
+) -> None:
+    """Root callback — exists only to hold the --version option.
+
+    Typer invokes the eager _version_callback before any subcommand
+    dispatch; there is nothing else to do at the app level.
+    """
+
+
+@app.command("explain")
+def explain(topic: str = typer.Argument(..., help="Topic to explain.")) -> None:
+    stdout, exit_code, stderr = explain_script.run(topic)
+    if stdout:
+        typer.echo(stdout, nl=False)
+    if stderr:
+        typer.echo(stderr, err=True)
+    if exit_code != 0:
+        raise typer.Exit(code=exit_code)
+
+
+def _agent_option() -> Any:
+    return typer.Option(..., "--agent", help="Backend: claude-code, codex, copilot, or acp.")
+
+
+hook_app = typer.Typer(help="Write and read agex tracking events.", no_args_is_help=True)
+app.add_typer(hook_app, name="hook")
+
+
+@hook_app.command("write")
+def hook_write(
+    event: str = typer.Argument(..., help="Event name (e.g., post-tool-use)."),
+    args: list[str] = typer.Argument(None, help="Additional key=value pairs."),
+) -> None:
+    args = args or []
+    _, exit_code, stderr = hook_write_script.run(event, args)
+    if stderr:
+        typer.echo(stderr, err=True)
+    if exit_code != 0:
+        raise typer.Exit(code=exit_code)
+
+
+@hook_app.command("read")
+def hook_read(agent: str = _agent_option()) -> None:
+    try:
+        backend = parse_backend(agent)
+    except ValueError as e:
+        typer.echo(f"agex: error: {e}", err=True)
+        raise typer.Exit(code=2)
+    stdout, exit_code, stderr = hook_read_script.run(backend)
+    if stdout:
+        typer.echo(stdout, nl=False)
+    if stderr:
+        typer.echo(stderr, err=True)
+    if exit_code != 0:
+        raise typer.Exit(code=exit_code)
+
+
+@app.command("learn")
+def learn(
+    topic: Optional[str] = typer.Argument(None, help="Lesson topic (omit for menu)."),
+    agent: str = _agent_option(),
+) -> None:
+    try:
+        backend = parse_backend(agent)
+    except ValueError as e:
+        typer.echo(f"agex: error: {e}", err=True)
+        raise typer.Exit(code=2)
+    if topic is None:
+        stdout, exit_code, stderr = learn_script.run_menu(backend)
+    else:
+        stdout, exit_code, stderr = learn_script.run_topic(topic, backend)
+    if stdout:
+        typer.echo(stdout, nl=False)
+    if stderr:
+        typer.echo(stderr, err=True)
+    if exit_code != 0:
+        raise typer.Exit(code=exit_code)
+
+
+@app.command("gamify")
+def gamify(
+    agent: str = _agent_option(),
+    uninstall: bool = typer.Option(False, "--uninstall", help="Reverse gamify."),
+) -> None:
+    try:
+        backend = parse_backend(agent)
+    except ValueError as e:
+        typer.echo(f"agex: error: {e}", err=True)
+        raise typer.Exit(code=2)
+    if uninstall:
+        stdout, exit_code, stderr = gamify_script.uninstall(backend)
+    else:
+        stdout, exit_code, stderr = gamify_script.install(backend)
+    if stdout:
+        typer.echo(stdout, nl=False)
+    if stderr:
+        typer.echo(stderr, err=True)
+    if exit_code != 0:
+        raise typer.Exit(code=exit_code)
+
+
+@app.command("overview")
+def overview(agent: str = _agent_option()) -> None:
+    try:
+        backend = parse_backend(agent)
+    except ValueError as e:
+        typer.echo(f"agex: error: {e}", err=True)
+        raise typer.Exit(code=2)
+    stdout, exit_code, stderr = overview_script.run(backend)
+    if stdout:
+        typer.echo(stdout, nl=False)
+    if stderr:
+        typer.echo(stderr, err=True)
+    if exit_code != 0:
+        raise typer.Exit(code=exit_code)
+
+
+# Keep in sync with the @app.command / app.add_typer registrations above.
+# If a new top-level command is added, extend this set so _main_entrypoint
+# stops routing it to the unknown-command fallback page.
+_KNOWN_COMMANDS = {"explain", "overview", "learn", "gamify", "hook"}
+
+
+def _main_entrypoint() -> None:
+    """CLI entry point that routes unknown subcommands to ``agex explain agex``.
+
+    When the first positional argument is not a known command (and is not a
+    flag), this function prints the ``agex explain agex`` page to stdout and
+    the canonical error message to stderr, then exits with code 2.  All other
+    invocations — known commands, ``--version``, ``--help``, zero-arg help —
+    fall through to the normal Typer ``app()`` dispatch unchanged.
+    """
+    argv = sys.argv[1:]
+    if argv and not argv[0].startswith("-") and argv[0] not in _KNOWN_COMMANDS:
+        typer.echo(f"agex: error: unknown command '{argv[0]}'", err=True)
+        stdout, _, _ = explain_script.run("agex")
+        typer.echo(stdout, nl=False)
+        sys.exit(2)
+    app()

agent_experience/commands/explain/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: explain
+description: Emit markdown documentation for any agex command, lesson, or concept.
+type: command
+---
+
+# `agex explain <topic>`
+
+Use this to get authoritative, deterministic documentation on an agex command, lesson, or concept without invoking a lesson or running a probe.
+
+## How it resolves
+
+1. `commands/<topic>/SKILL.md` (command-level, wins if present)
+2. `commands/learn/assets/topics/<topic>/SKILL.md` (lesson-level)
+3. `commands/explain/assets/topics/<topic>.md` (concept-level override)
+
+First match wins.
+
+## From your shell tool
+
+```bash
+agex explain overview
+agex explain gamify
+agex explain levelup
+agex explain agex          # self-describing page
+```

agent_experience/commands/explain/assets/topics/agex.md

@@ -0,0 +1,35 @@
+# `agex` — agent-operated developer-experience CLI
+
+`agex` is a non-agentic Python CLI that emits deterministic per-backend markdown for autonomous agents. You (the agent) invoke it from your shell tool to learn about and configure your own runtime.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `agex overview --agent X` | Snapshot of the project's current setup for backend X. |
+| `agex learn --agent X` | Menu of lesson topics available for backend X. |
+| `agex learn <topic> --agent X` | Teach a lesson (e.g., introspect, visualize, gamify, levelup). |
+| `agex gamify --agent X` | Install usage-tracking hooks (or unsupported notice). |
+| `agex gamify --uninstall --agent X` | Reverse `gamify`. |
+| `agex hook write <event> [...]` | Append a tracking event. Called by installed hooks. |
+| `agex hook read --agent X` | Show tracked events as markdown + source path. |
+| `agex explain <topic>` | You're reading this. |
+
+## First steps
+
+```bash
+agex explain agex              # this page
+agex learn --agent claude-code  # what can I learn for my backend?
+agex overview --agent claude-code  # what's in this project?
+```
+
+## Design invariants
+
+- **Non-agentic.** Zero LLM calls inside agex. All output is deterministic.
+- **Markdown is the universal format.** No `--json` flag.
+- **`--agent` is required** on backend-sensitive commands.
+- **Unsupported is success.** If your backend lacks a feature, you get a markdown notice + link to file an issue — exit code 0.
+
+## Repo
+
+<https://github.com/OriNachum/agex>

agent_experience/commands/explain/scripts/explain.py

@@ -0,0 +1,63 @@
+import re
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+
+from agent_experience.core.skill_loader import Skill, load_skill
+
+_TOPIC_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+
+
+def _commands_root() -> Traversable:
+    return files("agent_experience.commands")
+
+
+def resolve_topic(topic: str) -> tuple[str, Traversable] | None:
+    """Resolve topic per spec precedence. Returns (kind, traversable) or None.
+
+    Rejects any topic that isn't a simple slug to prevent path traversal.
+    """
+    if not _TOPIC_RE.match(topic):
+        return None
+
+    cmds = _commands_root()
+
+    cmd_skill = cmds.joinpath(topic, "SKILL.md")
+    if cmd_skill.is_file():
+        return ("command", cmd_skill)
+
+    lesson_skill = cmds.joinpath("learn", "assets", "topics", topic, "SKILL.md")
+    if lesson_skill.is_file():
+        return ("lesson", lesson_skill)
+
+    concept = cmds.joinpath("explain", "assets", "topics", f"{topic}.md")
+    if concept.is_file():
+        return ("concept", concept)
+
+    return None
+
+
+def _load_skill_from_traversable(trav: Traversable) -> Skill:
+    # load_skill expects a pathlib.Path; resolve via as_file when needed. Since
+    # our package resources are on a real filesystem (hatch force-include), the
+    # Traversable is a MultiplexedPath / PosixPath wrapper whose .read_text()
+    # works directly. We rebuild a Skill by parsing the body in-line to avoid
+    # Path coupling.
+    from importlib.resources import as_file
+
+    with as_file(trav) as path:
+        return load_skill(path)
+
+
+def run(topic: str) -> tuple[str, int, str]:
+    """Return (stdout, exit_code, stderr)."""
+    resolved = resolve_topic(topic)
+    if resolved is None:
+        agex_page = _commands_root().joinpath("explain", "assets", "topics", "agex.md")
+        body = agex_page.read_text(encoding="utf-8") if agex_page.is_file() else ""
+        return (body, 2, f"agex: error: unknown topic '{topic}'")
+
+    kind, trav = resolved
+    if kind == "concept":
+        return (trav.read_text(encoding="utf-8"), 0, "")
+    skill = _load_skill_from_traversable(trav)
+    return (skill.body, 0, "")

agent_experience/commands/gamify/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: gamify
+description: Install or uninstall backend-native hooks that track usage via agex hook write.
+type: command
+---
+
+# `agex gamify --agent <backend>` / `agex gamify --uninstall --agent <backend>`
+
+## What it does
+
+Writes backend-native hook fragments (each tagged with a stable `agex:*` ID) that call `agex hook write <event>` on PostToolUse, UserPromptSubmit, and Stop events. Agent-authored skills (e.g., `levelup`) read the accumulated data via `agex hook read`.
+
+## Why it's safe
+
+- Idempotent: re-running is a no-op.
+- Reversible: `--uninstall` removes exactly the `agex:*` fragments; user-authored hooks are untouched.
+- Calling `agex gamify` explicitly is the confirmation — no separate prompt.
+
+## Unsupported backends
+
+If your backend doesn't support hooks, you get a markdown notice + issue link instead.
+
+## From your shell tool
+
+```bash
+agex gamify --agent claude-code
+# ... use your runtime for a while ...
+agex hook read --agent claude-code
+# ... later, to undo:
+agex gamify --uninstall --agent claude-code
+```

agent_experience/commands/gamify/assets/hooks/claude-code.json

@@ -0,0 +1,28 @@
+{
+  "fragments": [
+    {
+      "id": "agex:post-tool-use",
+      "event": "PostToolUse",
+      "hook": {
+        "type": "command",
+        "command": "agex hook write post-tool-use tool=\"$CLAUDE_TOOL_NAME\""
+      }
+    },
+    {
+      "id": "agex:user-prompt",
+      "event": "UserPromptSubmit",
+      "hook": {
+        "type": "command",
+        "command": "agex hook write user-prompt"
+      }
+    },
+    {
+      "id": "agex:stop",
+      "event": "Stop",
+      "hook": {
+        "type": "command",
+        "command": "agex hook write stop"
+      }
+    }
+  ]
+}