crossagent 0.1.0__py3-none-any.whl

crossagent/__init__.py

@@ -0,0 +1,3 @@
+"""crossagent — get a second opinion from another AI coding agent."""
+
+__version__ = "0.1.0"

crossagent/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

crossagent/advisors.py

@@ -0,0 +1,166 @@
+"""Advisor registry: how to invoke each peer coding-agent CLI.
+
+An *advisor* is a peer AI agent you ask for a second opinion (Claude, Codex,
+OpenCode, CommandCode, Gemini, ...). Each entry is a small, declarative spec that
+tells the runner how to build the command line, where the prompt goes, and how to
+read the result back out. Built-ins ship sane defaults; users override or add their
+own via ~/.config/crossagent/advisors.json without touching code.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+# Where the prompt string is placed on the argv.
+#   "dashdash"   -> [..., "--", prompt]        (claude: everything after -- is the prompt)
+#   "positional" -> [..., prompt]              (codex exec / opencode run)
+#   "flag:-p"    -> [..., "-p", prompt]        (gemini: prompt is the value of -p)
+PROMPT_DELIVERIES = frozenset({"dashdash", "positional"})
+
+# How to read the advisor's answer back out of its stdout.
+#   "claude-stream" -> parse newline-delimited stream-json events, take the result event
+#   "text"          -> capture raw stdout as the answer
+RESULT_PARSERS = frozenset({"claude-stream", "text"})
+
+USER_CONFIG = Path.home() / ".config" / "crossagent" / "advisors.json"
+
+
+@dataclass(frozen=True)
+class Advisor:
+    """Declarative recipe for invoking one peer-agent CLI."""
+
+    name: str
+    executable: str
+    base_args: tuple[str, ...] = ()
+    invoke_args: tuple[str, ...] = ()
+    prompt_delivery: str = "positional"  # "dashdash" | "positional" | "flag:<flag>"
+    model_flag: str | None = None
+    stream_args: tuple[str, ...] = ()
+    json_args: tuple[str, ...] = ()
+    resume_flag: str | None = None
+    session_name_flag: str | None = None
+    fork_flag: str | None = None
+    result_parser: str = "text"
+    experimental: bool = False
+    notes: str = ""
+
+    @property
+    def supports_sessions(self) -> bool:
+        return self.resume_flag is not None or self.session_name_flag is not None
+
+    @property
+    def supports_stream(self) -> bool:
+        return self.result_parser == "claude-stream"
+
+
+# --- Built-in advisors -------------------------------------------------------
+# claude is the reference implementation: fully featured, verified against the
+# upstream `claude -p` behaviour. The rest are pragmatic best-effort defaults —
+# marked experimental — that users can correct via the JSON override file.
+
+_BUILTINS: dict[str, Advisor] = {
+    "claude": Advisor(
+        name="claude",
+        executable="claude",
+        invoke_args=("-p",),
+        prompt_delivery="dashdash",
+        model_flag="--model",
+        stream_args=("--verbose", "--output-format", "stream-json"),
+        json_args=("--output-format", "json"),
+        resume_flag="--resume",
+        session_name_flag="--name",
+        fork_flag="--fork-session",
+        result_parser="claude-stream",
+    ),
+    "codex": Advisor(
+        name="codex",
+        executable="codex",
+        base_args=("exec",),
+        prompt_delivery="positional",
+        model_flag="--model",
+        result_parser="text",
+        experimental=True,
+        notes="Uses `codex exec <prompt>` (non-interactive). Resume not wired by default.",
+    ),
+    "opencode": Advisor(
+        name="opencode",
+        executable="opencode",
+        base_args=("run",),
+        prompt_delivery="positional",
+        model_flag="--model",
+        result_parser="text",
+        experimental=True,
+        notes="Uses `opencode run <prompt>` (headless).",
+    ),
+    "commandcode": Advisor(
+        name="commandcode",
+        executable="commandcode",
+        invoke_args=("-p",),
+        prompt_delivery="positional",
+        model_flag="--model",
+        result_parser="text",
+        experimental=True,
+        notes="Uses `commandcode -p <prompt>` (non-interactive). Resume not wired by default.",
+    ),
+    "gemini": Advisor(
+        name="gemini",
+        executable="gemini",
+        prompt_delivery="flag:-p",
+        model_flag="--model",
+        result_parser="text",
+        experimental=True,
+        notes="Uses `gemini -p <prompt>` (non-interactive).",
+    ),
+}
+
+# Friendly aliases callers may type.
+_ALIASES = {"cmd": "commandcode", "cc": "claude", "oc": "opencode"}
+
+
+def _coerce(name: str, raw: dict[str, Any]) -> Advisor:
+    """Build an Advisor from a user-config dict, layering onto a built-in if one exists."""
+    base = _BUILTINS.get(name, Advisor(name=name, executable=raw.get("executable", name)))
+    tuple_fields = {"base_args", "invoke_args", "stream_args", "json_args"}
+    overrides: dict[str, Any] = {}
+    for key, value in raw.items():
+        if key in tuple_fields and isinstance(value, list):
+            overrides[key] = tuple(value)
+        elif key != "name":
+            overrides[key] = value
+    return replace(base, name=name, **overrides)
+
+
+def _load_user_config(path: Path) -> dict[str, Advisor]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+    entries = data.get("advisors", data) if isinstance(data, dict) else {}
+    result: dict[str, Advisor] = {}
+    if isinstance(entries, dict):
+        for name, raw in entries.items():
+            if isinstance(raw, dict):
+                result[name] = _coerce(name, raw)
+    return result
+
+
+def available(config_path: Path | None = None) -> dict[str, Advisor]:
+    """Return the merged advisor registry: built-ins overridden by user config."""
+    merged = dict(_BUILTINS)
+    merged.update(_load_user_config(config_path or USER_CONFIG))
+    return merged
+
+
+def resolve(name: str, config_path: Path | None = None) -> Advisor:
+    """Look up an advisor by name or alias. Raises KeyError with a helpful message."""
+    canonical = _ALIASES.get(name.strip().lower(), name.strip().lower())
+    registry = available(config_path)
+    if canonical not in registry:
+        known = ", ".join(sorted(registry))
+        raise KeyError(f"Unknown advisor '{name}'. Known advisors: {known}. Add your own in {USER_CONFIG}.")
+    return registry[canonical]

crossagent/cli.py

@@ -0,0 +1,240 @@
+"""Run a named, resumable second-opinion session with a peer coding-agent CLI.
+
+`crossagent` lets one AI coding agent get a second opinion from another. It builds
+the right command for the chosen advisor (Claude by default), keeps the process
+alive until the advisor finishes, streams progress to stderr, prints the final
+answer to stdout, and remembers the session so a follow-up can resume it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import advisors as advisors_mod
+from . import registry as reg
+from .advisors import Advisor
+
+
+def read_prompt(args: argparse.Namespace) -> str:
+    if args.prompt_file:
+        return Path(args.prompt_file).read_text(encoding="utf-8")
+    if args.prompt:
+        return args.prompt
+    if not sys.stdin.isatty():
+        return sys.stdin.read()
+    raise SystemExit("Provide --prompt-file, --prompt, or pipe the prompt on stdin.")
+
+
+def _append_prompt(cmd: list[str], advisor: Advisor, prompt: str) -> None:
+    delivery = advisor.prompt_delivery
+    if delivery == "dashdash":
+        cmd.extend(["--", prompt])
+    elif delivery.startswith("flag:"):
+        cmd.extend([delivery.split(":", 1)[1], prompt])
+    else:  # "positional"
+        cmd.append(prompt)
+
+
+def _redacted_command(cmd: list[str]) -> str:
+    """Format an advisor command without exposing its final prompt argument."""
+    if not cmd:
+        return "<prompt>"
+    return shlex.join([*cmd[:-1], "<prompt>"])
+
+
+def build_command(advisor: Advisor, args: argparse.Namespace, registry: dict[str, Any]) -> tuple[list[str], str]:
+    cmd = [advisor.executable, *advisor.base_args, *advisor.invoke_args]
+
+    if args.model and advisor.model_flag:
+        cmd.extend([advisor.model_flag, args.model])
+
+    if advisor.supports_stream:
+        cmd.extend(args.stream and advisor.stream_args or advisor.json_args)
+        if args.stream and args.partial:
+            cmd.append("--include-partial-messages")
+
+    if args.safe_mode:
+        cmd.append("--safe-mode")
+    if args.permission_mode:
+        cmd.extend(["--permission-mode", args.permission_mode])
+    if args.tools is not None:
+        cmd.extend(["--tools", args.tools])
+    for allowed in args.allowed_tools:
+        cmd.extend(["--allowedTools", allowed])
+    if args.system_prompt:
+        cmd.extend(["--system-prompt", args.system_prompt])
+    for extra in args.raw_arg:
+        cmd.append(extra)
+
+    key = reg.session_key(advisor.name, args.name)
+    stored_id = reg.stored_session_id(registry, key)
+
+    if advisor.supports_sessions:
+        if args.resume and advisor.resume_flag:
+            cmd.extend([advisor.resume_flag, args.resume])
+        elif stored_id and not args.new_session and advisor.resume_flag:
+            cmd.extend([advisor.resume_flag, stored_id])
+        elif args.name and advisor.session_name_flag:
+            cmd.extend([advisor.session_name_flag, args.name])
+        if args.fork_session and advisor.fork_flag:
+            cmd.append(advisor.fork_flag)
+
+    _append_prompt(cmd, advisor, prompt=args._prompt)
+    return cmd, key
+
+
+# --- Claude stream-json handling --------------------------------------------
+
+def summarize_event(event: dict[str, Any]) -> None:
+    kind = event.get("type")
+    if kind == "system" and event.get("subtype") == "init":
+        print(f"[crossagent] init session={event.get('session_id')} model={event.get('model')} "
+              f"cwd={event.get('cwd')}", file=sys.stderr)
+    elif kind == "assistant":
+        message = event.get("message", {})
+        blocks = message.get("content", []) if isinstance(message, dict) else []
+        text = "".join(b.get("text", "") for b in blocks
+                       if isinstance(b, dict) and b.get("type") == "text")
+        if text:
+            print(f"[crossagent] assistant: {text.replace(chr(10), ' ')[:240]}", file=sys.stderr)
+    elif kind == "result":
+        print(f"[crossagent] result subtype={event.get('subtype')} session={event.get('session_id')} "
+              f"cost={event.get('total_cost_usd')}", file=sys.stderr)
+    elif kind == "rate_limit_event":
+        info = event.get("rate_limit_info", {})
+        print(f"[crossagent] rate_limit status={info.get('status')} resetsAt={info.get('resetsAt')}",
+              file=sys.stderr)
+
+
+def _run_stream(cmd: list[str], cwd: str | None) -> tuple[int, dict[str, Any] | None]:
+    proc = subprocess.Popen(cmd, cwd=cwd, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                            text=True, bufsize=1)
+    assert proc.stdout is not None and proc.stderr is not None
+    final: dict[str, Any] | None = None
+    for line in proc.stdout:
+        stripped = line.strip()
+        if not stripped:
+            continue
+        try:
+            event = json.loads(stripped)
+        except json.JSONDecodeError:
+            print(stripped, file=sys.stderr)
+            continue
+        summarize_event(event)
+        if event.get("type") == "result":
+            final = event
+    err = proc.stderr.read()
+    if err:
+        print(err, file=sys.stderr, end="")
+    return proc.wait(), final
+
+
+def _run_text(cmd: list[str], cwd: str | None) -> tuple[int, str]:
+    completed = subprocess.run(cmd, cwd=cwd, text=True, capture_output=True, check=False)
+    if completed.stderr:
+        print(completed.stderr, file=sys.stderr, end="")
+    return completed.returncode, completed.stdout
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="crossagent", description=__doc__)
+    parser.add_argument("--agent", "--advisor", dest="agent", default="claude",
+                        help="Peer agent to ask: claude, codex, opencode, commandcode, gemini, or a custom advisor. Default: claude.")
+    parser.add_argument("--name", help="Stable session name. Reused names auto-resume the stored session.")
+    parser.add_argument("--resume", help="Force a --resume target: session id or search term.")
+    parser.add_argument("--new-session", action="store_true", help="Ignore any stored session for --name and start fresh.")
+    parser.add_argument("--fork-session", action="store_true", help="Fork a new session from the existing conversation.")
+    parser.add_argument("--prompt-file", help="Path to the second-opinion prompt.")
+    parser.add_argument("--prompt", help="Prompt text. Prefer --prompt-file for long prompts.")
+    parser.add_argument("--cwd", help="Working directory for the advisor. Defaults to the current directory.")
+    parser.add_argument("--model", default="", help="Advisor model or alias (advisor-specific). Empty = advisor default.")
+    parser.add_argument("--safe-mode", action="store_true", help="Claude: run with --safe-mode (skip repo config/skills/hooks).")
+    parser.add_argument("--no-stream", dest="stream", action="store_false", help="Claude: use single JSON output instead of streaming.")
+    parser.add_argument("--partial", action="store_true", help="Claude: include partial stream messages.")
+    parser.add_argument("--tools", help='Claude: pass --tools, e.g. "" for none or "Read,Bash".')
+    parser.add_argument("--allowed-tools", action="append", default=[], help="Claude: repeatable --allowedTools value.")
+    parser.add_argument("--permission-mode", help="Claude: --permission-mode value.")
+    parser.add_argument("--system-prompt", help="Claude: --system-prompt value.")
+    parser.add_argument("--raw-arg", action="append", default=[], help="Repeatable raw argument passed straight to the advisor CLI.")
+    parser.add_argument("--registry", default=str(reg.DEFAULT_REGISTRY), help="Session registry path.")
+    parser.add_argument("--list-advisors", action="store_true", help="Print known advisors and exit.")
+    parser.set_defaults(stream=True)
+    return parser.parse_args(argv)
+
+
+def _print_advisors() -> int:
+    for name, adv in sorted(advisors_mod.available().items()):
+        tag = " (experimental)" if adv.experimental else ""
+        print(f"{name:14} -> {adv.executable}{tag}")
+        if adv.notes:
+            print(f"{'':14}    {adv.notes}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    if args.list_advisors:
+        return _print_advisors()
+
+    try:
+        advisor = advisors_mod.resolve(args.agent)
+    except KeyError as exc:
+        print(f"[crossagent] {exc}", file=sys.stderr)
+        return 2
+
+    if advisor.experimental:
+        print(f"[crossagent] advisor '{advisor.name}' is experimental — verify flags for your install.",
+              file=sys.stderr)
+
+    args._prompt = read_prompt(args)
+    registry_path = Path(args.registry).expanduser()
+    registry = reg.load(registry_path)
+    cmd, key = build_command(advisor, args, registry)
+
+    print(f"[crossagent] running: {_redacted_command(cmd)}", file=sys.stderr)
+
+    try:
+        return _dispatch(advisor, args, cmd, key, registry, registry_path)
+    except FileNotFoundError:
+        print(f"[crossagent] advisor CLI not found on PATH: '{advisor.executable}'. "
+              f"Install it, or point '{advisor.name}' at the right executable in "
+              f"{advisors_mod.USER_CONFIG}.", file=sys.stderr)
+        return 127
+
+
+def _dispatch(advisor: Advisor, args: argparse.Namespace, cmd: list[str], key: str,
+              registry: dict[str, Any], registry_path: Path) -> int:
+    if advisor.supports_stream and args.stream:
+        code, final = _run_stream(cmd, args.cwd)
+        if final:
+            if final.get("is_error"):
+                errors = final.get("errors") or final.get("api_error_status") or "unknown error"
+                print(f"[crossagent] {advisor.name} returned error: {errors}", file=sys.stderr)
+            result = final.get("result")
+            structured = final.get("structured_output")
+            if result:
+                print(result)
+            elif structured is not None:
+                print(json.dumps(structured, indent=2, sort_keys=True))
+            session_id = final.get("session_id")
+            if key and session_id:
+                reg.record(registry_path, registry, key, session_id=session_id, name=args.name,
+                           cwd=args.cwd or os.getcwd(), advisor=advisor.name, model=args.model)
+                print(f"[crossagent] saved session name={key} id={session_id}", file=sys.stderr)
+        return code
+
+    code, out = _run_text(cmd, args.cwd)
+    if out.strip():
+        print(out, end="" if out.endswith("\n") else "\n")
+    return code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

crossagent/registry.py

@@ -0,0 +1,72 @@
+"""Named, resumable second-opinion sessions.
+
+Stores each session's underlying session id keyed by ``advisor:slug`` so a
+later turn on the same decision can resume the same conversation. Only advisors
+that emit a session id (currently Claude) populate this; the file is otherwise a
+harmless no-op.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+DEFAULT_REGISTRY = Path.home() / ".config" / "crossagent" / "sessions.json"
+
+
+def slugify(value: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9._-]+", "-", value.strip().lower())
+    slug = re.sub(r"-{2,}", "-", slug).strip("-")
+    return slug or "second-opinion"
+
+
+def session_key(advisor: str, name: str | None) -> str:
+    return f"{advisor}:{slugify(name)}" if name else ""
+
+
+def load(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {"sessions": {}}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        backup = path.with_suffix(path.suffix + ".corrupt")
+        path.replace(backup)
+        print(f"[crossagent] Registry was invalid JSON; moved to {backup}", file=sys.stderr)
+        return {"sessions": {}}
+    if not isinstance(data, dict):
+        return {"sessions": {}}
+    if not isinstance(data.get("sessions"), dict):
+        data["sessions"] = {}
+    return data
+
+
+def save(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def stored_session_id(registry: dict[str, Any], key: str) -> str | None:
+    entry = registry.get("sessions", {}).get(key) if key else None
+    return entry.get("session_id") if isinstance(entry, dict) else None
+
+
+def record(path: Path, registry: dict[str, Any], key: str, *, session_id: str, name: str | None,
+           cwd: str, advisor: str, model: str) -> dict[str, Any]:
+    """Return a NEW registry dict with the session recorded, and persist it."""
+    sessions = dict(registry.get("sessions", {}))
+    sessions[key] = {
+        "session_id": session_id,
+        "name": name,
+        "advisor": advisor,
+        "cwd": str(Path(cwd).resolve()),
+        "model": model,
+        "updated_at": datetime.now(timezone.utc).isoformat(),
+    }
+    updated = {**registry, "sessions": sessions}
+    save(path, updated)
+    return updated

crossagent-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: crossagent
+Version: 0.1.0
+Summary: Get a second opinion from another AI coding agent. Ask Claude, Codex, OpenCode, CommandCode, or Gemini — from inside the agent you already use.
+Project-URL: Homepage, https://github.com/datj9/crossagent
+Project-URL: Repository, https://github.com/datj9/crossagent
+Project-URL: Issues, https://github.com/datj9/crossagent/issues
+Project-URL: Changelog, https://github.com/datj9/crossagent/blob/main/CHANGELOG.md
+Author: Dat Nguyen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude,cli,codex,coding-agent,mcp,opencode,second-opinion
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# crossagent
+
+**Get a second opinion from another AI agent — without leaving the one you're in.**
+
+`crossagent` lets your coding agent (Claude Code, Codex, Cursor, Cline, OpenCode, CommandCode…) pause and ask a *different* agent to independently evaluate a hard call — an architecture decision, a gnarly bug, a prompt rewrite — then hands you both viewpoints so **you** decide. One agent proposes; another one challenges. You get the disagreement, not just an echo.
+
+```bash
+crossagent --agent claude --name payments-retry-design --prompt-file /tmp/decision.md
+```
+
+- 🤝 **Cross-agent, by design.** Ask **Claude, Codex, OpenCode, CommandCode, or Gemini** — from inside whichever agent you already use.
+- 🧠 **A teammate, not an oracle.** Ships a second-opinion protocol that forces an evidence-backed critique with cited files, risks, and a recommendation — then a synthesis step, so the second opinion sharpens *your* judgment instead of replacing it.
+- 🔁 **Named, resumable Claude sessions.** Reuse a name to continue the same decision; fork to explore a branch. No re-explaining context every turn.
+- 📡 **Long-running & streamed.** No default timeout, no default cost cap. It waits until the advisor finishes and streams progress as it goes.
+- 🧩 **Agent Skill + CLI.** Installs as an [Agent Skill](https://agentskills.dev) *and* a standalone `crossagent` command. Zero runtime dependencies.
+- 🔓 **Local & open.** Runs entirely on your machine against CLIs you already have. MIT licensed.
+
+---
+
+## Why
+
+Coding agents are confident. That's the problem. The same model that writes the code also reviews it, so a plausible-but-wrong call sails straight through. The fix engineers already use with each other — *"let me get a second pair of eyes"* — works for agents too, but only if the second agent is **actually different** and is briefed well enough to disagree on the merits.
+
+`crossagent` makes that a one-liner. Package the decision, hand it to a peer agent, get back a structured critique — Position / Evidence / Risks / Recommendation / Unresolved — and reconcile it with your own view before you commit.
+
+## Install
+
+Install the CLI from PyPI (using `pipx` keeps command-line applications isolated):
+
+```bash
+pipx install crossagent
+# or: pip install crossagent
+
+crossagent --list-advisors
+```
+
+You also need at least one advisor CLI on your PATH — e.g. [`claude`](https://docs.claude.com/claude-code), `codex`, `opencode`, `commandcode`, or `gemini`.
+
+To install both the CLI and the Agent Skill from the repository:
+
+```bash
+git clone https://github.com/datj9/crossagent.git
+cd crossagent
+./install.sh
+```
+
+The installer checks the supported agent config dirs (`~/.claude`, `~/.codex`, `~/.config/opencode`, `~/.commandcode`, `~/.cursor`), installs the skill into those present, and installs the CLI via `pipx`/`pip`.
+
+## Quick start
+
+Write a compact decision brief, then ask a peer:
+
+```bash
+cat > /tmp/decision.md <<'EOF'
+<decision>Should the payment retry live in the worker or the API layer?</decision>
+<current_state>Retries currently inline in the API handler; p99 latency regressed 40%.</current_state>
+<constraints>No new infra this quarter. Must stay idempotent.</constraints>
+<evidence>src/api/payments.ts:88, worker/queue.ts:12, load test in bench/2026-07.md</evidence>
+<questions>1. Which layer, and why? 2. Strongest counterargument? 3. Cheapest validation?</questions>
+EOF
+
+crossagent --agent claude --name payments-retry-design --cwd "$PWD" --prompt-file /tmp/decision.md
+```
+
+The advisor's answer prints to **stdout**; progress and session metadata go to **stderr**. Continue the same decision later — context is remembered:
+
+```bash
+crossagent --name payments-retry-design --prompt-file /tmp/followup.md   # auto-resumes
+crossagent --name payments-retry-design --fork-session --prompt-file /tmp/alt.md  # branch it
+```
+
+Or let your agent do it for you — just say *"ask Claude about this"* / *"hỏi ý với Claude"* / *"get a second opinion from Codex"* and the skill fires.
+
+## How it works
+
+```
+your agent ──▶ crossagent CLI ──▶ peer agent's CLI (claude -p / codex exec / …)
+     ▲              │                     │
+     └── synthesis ─┴──── streamed ◀──────┘
+         (you reconcile both views)       result + session id
+```
+
+1. You (or your agent) package the decision using the [second-opinion protocol](skills/crossagent/references/second-opinion-protocol.md).
+2. `crossagent` builds the right command for the chosen advisor and keeps it alive until it exits.
+3. For session-capable advisors, it stores the `session_id` keyed by `advisor:name` so the next turn resumes.
+4. You compare the two viewpoints and make the call.
+
+## Advisors
+
+| Advisor | Command | Status | Sessions |
+|---|---|---|---|
+| `claude` | `claude -p` | ✅ full | resume, name, fork, streamed |
+| `codex` | `codex exec` | 🧪 experimental | text output |
+| `opencode` | `opencode run` | 🧪 experimental | text output |
+| `commandcode` | `commandcode -p` | 🧪 experimental | text output |
+| `gemini` | `gemini -p` | 🧪 experimental | text output |
+
+Experimental advisors ship best-effort default flags. If your install differs, fix them without touching code — see below.
+
+### Add or fix an advisor
+
+Create `~/.config/crossagent/advisors.json`:
+
+```json
+{
+  "advisors": {
+    "codex": { "executable": "codex", "base_args": ["exec", "--full-auto"] },
+    "myllm": { "executable": "myllm", "prompt_delivery": "flag:-q", "model_flag": "--model" }
+  }
+}
+```
+
+Fields layer onto the built-ins, so you only specify what differs. `prompt_delivery` is `dashdash` (prompt after `--`), `positional` (prompt as last arg), or `flag:<flag>` (prompt is the value of a flag).
+
+## Skill usage inside an agent
+
+Once installed, the skill auto-triggers on phrases like *"ask Claude"*, *"debate with Claude"*, *"ask Codex"*, *"second opinion"*, *"hỏi ý với Claude"*. The agent packages context, runs `crossagent`, and reports both views. See [`skills/crossagent/SKILL.md`](skills/crossagent/SKILL.md).
+
+## Examples
+
+- [Architecture decision](examples/architecture-decision.md)
+- [Debugging second opinion](examples/debug-second-opinion.md)
+
+## Security
+
+- Secrets never belong in prompts, CLI args, logs, or copied context — the protocol says so and you should enforce it.
+- Second-opinion sessions run read-only by convention; for Claude use `--tools ""` for pure reasoning or restrict with `--allowedTools`.
+- Everything runs locally against CLIs you already trust. `crossagent` adds no network calls of its own.
+
+## Contributing
+
+Issues and PRs welcome — especially hardening the experimental advisors against real installs. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT © Dat Nguyen. See [LICENSE](LICENSE).

crossagent-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+crossagent/__init__.py,sha256=5hRebZC4Xy9EZUJt5T3Rm9sZsOZUM0-lO7y0oYZ1RR8,95
+crossagent/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+crossagent/advisors.py,sha256=sH39ZgMee4rW3NHt5y6BlkPjGco6joijZ1kmCrbi6qE,6153
+crossagent/cli.py,sha256=8NOz_Q9SQYHO8O-VOt_2cAjbcXm2oO3F9eAwLDjPQJ0,10594
+crossagent/registry.py,sha256=a21PAerkh3CYgI3KIPqVmY1Kb4rwhJ3Ww9ojkF-BgsU,2452
+crossagent-0.1.0.dist-info/METADATA,sha256=_deD8QC3bibmECd8u9QMgRTAelcqywOhZP5AWspRRek,8144
+crossagent-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+crossagent-0.1.0.dist-info/entry_points.txt,sha256=yZQFKz8V9dRliDyibszp5uTrmsID8HhU4ylJ9TFmWns,51
+crossagent-0.1.0.dist-info/licenses/LICENSE,sha256=8i4i2eLi11n7bvCGL4eOMBPaYV9azdtTDgOgPqBMrWc,1067
+crossagent-0.1.0.dist-info/RECORD,,

crossagent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

crossagent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+crossagent = crossagent.cli:main

crossagent-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dat Nguyen
+
+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.