Skip to content

YujunZhou/tellonce / codex

tellonce

Verified

Use to view, explain, correct, delete or reorganize the user's saved preferences, or to record one by hand when automatic recording is off; learning and rule injection otherwise run automatically through Codex hooks.

FileKindSize
.codex-plugin/plugin.jsonconfig1.3 KB
SKILL.mdskill md12.0 KB
dashboard.shexecutablescript348 B
docs/CC_PARITY_MATRIX.mdmarkdown7.3 KB
docs/README.mdmarkdown3.4 KB
doctor.shexecutablescript345 B
hooks/hooks.jsonconfig714 B
hooks/posttooluse-deterministic-block.shexecutablescript2.0 KB
hooks/sessionstart-init.shexecutablescript1.9 KB
hooks/userpromptsubmit-dispatch.pyscript2.6 KB
hooks/userpromptsubmit-memory-upsert.shscript326 B
hooks/userpromptsubmit-pending-inject.shexecutablescript2.0 KB
hooks/userpromptsubmit-retrieve-inject.shexecutablescript3.1 KB
hooks/userpromptsubmit-shadow-alert-inject.shexecutablescript1.2 KB
install.shexecutablescript13.9 KB
shared_lib/_install_merge_settings.pyscript12.1 KB
shared_lib/_pt_hooks.txtmarkdown407 B
shared_lib/correction_interpretation.pyscript8.5 KB
shared_lib/detect_user_prefer.pyscript7.2 KB
shared_lib/deterministic_block.pyscript9.3 KB
shared_lib/event_obligations.pyscript19.8 KB
shared_lib/execution_support.pyscript75.8 KB
shared_lib/fingerprints.yamlconfig1.1 KB
shared_lib/learning_policy.pyscript4.6 KB
shared_lib/memory_judge.pyscript84.8 KB
shared_lib/memory_publication.pyscript14.9 KB
shared_lib/memory_runtime.pyscript12.2 KB
shared_lib/memory_store.pyscript99.6 KB
shared_lib/memory_upsert.pyscript57.1 KB
shared_lib/memory_upsert_hook.pyscript4.6 KB
shared_lib/model_requests.pyscript5.8 KB
shared_lib/path_config.pyscript13.3 KB
shared_lib/pending_queue_manager.pyscript23.4 KB
shared_lib/pt_platform.pyscript1.5 KB
shared_lib/redaction.pyscript3.4 KB
shared_lib/retrieve_inject.pyexecutablescript57.9 KB
shared_lib/rule_selection.pyscript18.9 KB
shared_lib/shadow_alert_inject.pyscript6.1 KB
shared_lib/training_memory.pyscript17.8 KB
shared_lib/transcript_adapter.pyscript13.7 KB
shared_lib/verify_compliance.pyexecutablescript24.5 KB
shared_lib/verify_retry_shadow.pyscript27.4 KB
tellonce_codex/__init__.pyscript52 B
tellonce_codex/__main__.pyscript49 B
tellonce_codex/cli.pyscript6.8 KB
tellonce_codex/codex_posttooluse_block.pyscript11.2 KB
tellonce_codex/dashboard.pyscript3.4 KB
tellonce_codex/doctor.pyscript10.9 KB
tellonce_codex/index.pyscript1.8 KB
tellonce_codex/install.pyscript3.1 KB
tellonce_codex/install_codex_hooks.pyscript15.1 KB
tellonce_codex/ledger.pyscript17.1 KB
tellonce_codex/memory.pyscript5.3 KB
tellonce_codex/migrate.pyscript1.3 KB
tellonce_codex/mode.pyscript2.3 KB
tellonce_codex/paths.pyscript8.6 KB
tellonce_codex/promote.pyscript4.4 KB
tellonce_codex/scan.pyscript2.6 KB
tellonce_codex/uninstall.pyscript1.7 KB
tellonce_codex/verify.pyscript5.3 KB
tellonce_codex/wrapper.pyscript12.0 KB
uninstall.shexecutablescript4.6 KB

tellonce_codex/cli.py

View on GitHub
from __future__ import annotations

import argparse
import sys
from pathlib import Path

from .dashboard import build_dashboard
from .doctor import run_doctor
from .install import install
from .migrate import preview_migration
from .paths import ensure_registered, find_registration
from .promote import promote_candidate
from .scan import scan_message
from .uninstall import uninstall
from .wrapper import run_wrapped


COMMANDS = ("install", "doctor", "uninstall", "scan", "promote", "dashboard", "exec", "migrate")


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(prog="tellonce_codex")
    sub = parser.add_subparsers(dest="command")
    for command in COMMANDS:
        p = sub.add_parser(command)
        if command in {"install", "doctor", "uninstall", "scan", "promote", "dashboard", "exec", "migrate"}:
            p.add_argument("--project-root", default=".")
        if command == "scan":
            p.add_argument("--message", required=False, default="")
        if command == "promote":
            p.add_argument("--dry-run", action="store_true")
        if command == "migrate":
            p.add_argument("--preview", action="store_true")
            p.add_argument("--apply", action="store_true",
                           help="reserved; currently rejected because migration apply is not implemented")
            p.add_argument("--source", action="append", default=[])
        if command == "install":
            # Forward --no-hooks down so the
            # CLI install does not write ~/.codex/hooks.json. Default
            # remains register_hooks=True (matches install.sh phase 3
            # expectation when bash phase 2 already ran).
            p.add_argument("--no-hooks", action="store_true",
                           help="skip auto-registering hooks in ~/.codex/hooks.json (state init only)")
        if command == "uninstall":
            # CX-6: real --purge-state flag; default keeps data.
            p.add_argument("--purge-state", action="store_true",
                           help="DANGER: rm -rf the entire <project>/.codex/tellonce/ state directory.")
        if command == "exec":
            def _positive_int(s: str) -> int:
                v = int(s)
                if v <= 0:
                    raise argparse.ArgumentTypeError("--timeout must be > 0")
                return v
            p.add_argument("--timeout", type=_positive_int, default=None,
                           help="seconds to wait for the wrapped subprocess (default: env CODEX_PT_TIMEOUT or 600)")
            p.add_argument("cmd", nargs=argparse.REMAINDER)
    return parser


def main(argv: list[str] | None = None) -> int:
    if argv is None:
        argv = sys.argv[1:]
    parser = build_parser()
    if not argv:
        parser.print_usage(sys.stderr)
        return 2
    try:
        args = parser.parse_args(argv)
    except SystemExit as exc:
        return int(exc.code or 0)

    project_root = Path(args.project_root)

    if args.command == "install":
        install(project_root, register_hooks=not getattr(args, "no_hooks", False))
    elif args.command == "doctor":
        print(run_doctor(project_root).status_line)
    elif args.command == "uninstall":
        uninstall(project_root, keep_data=not args.purge_state)
    elif args.command == "scan":
        # CX-5: ensure_registered, not install — preserves mode.json across invocations.
        state = ensure_registered(project_root).state_root
        scan_message(state, args.message)
    elif args.command == "dashboard":
        registration = find_registration(project_root)
        if registration is None:
            print("Tellonce status: NOT_INSTALLED")
        else:
            print(build_dashboard(registration.state_root))
    elif args.command == "promote":
        if args.dry_run:
            # Placeholder candidate used only for smoke-level command viability.
            state = ensure_registered(project_root).state_root
            promote_candidate(
                state,
                {
                    "atomic_id": "dry-run",
                    "type": "preference",
                    "domain": "workflow",
                    "scope": "global",
                    "condition": "dry run",
                    "rule_text": "MUST dry run",
                    "applies_when": "dry run",
                    "does_not_apply_when": "(none)",
                    "confidence": "low",
                },
                dry_run=True,
            )
        else:
            print(
                "promote: --dry-run is the only supported CLI mode; programmatic callers "
                "must call tellonce_codex.promote.promote_candidate(..., "
                "source_text=<complete original user turn>) to queue through the "
                "shared SQLite upsert core.",
                file=sys.stderr,
            )
            return 2
    elif args.command == "migrate":
        # CX-13: don't silently no-op when neither flag is set.
        if not args.preview and not args.apply:
            print(
                "migrate: choose --preview to inspect decisions, or --apply to actually migrate.\n"
                "        sources may be passed via repeated --source.",
                file=sys.stderr,
            )
            return 2
        # W6 fix: preview_migration's first arg is `state_root` (it writes
        # `<state_root>/evidence/migration_preview.json` when write_report).
        # --preview is read-only — don't register or touch state_root at all.
        if args.preview:
            preview_migration(Path("/"), [Path(p) for p in args.source], write_report=False)
        else:
            print(
                "migrate --apply is not implemented; no state or preview was written. "
                "Use --preview to inspect sources.",
                file=sys.stderr,
            )
            return 2
    elif args.command == "exec":
        # CX-12: enforce `--` as the separator between tellonce_codex flags
        # and the wrapped command. Without it, argparse will swallow flags
        # like --project-root that the user intended to pass through.
        cmd = list(args.cmd)
        if cmd and cmd[0] == "--":
            cmd = cmd[1:]
        else:
            print(
                "exec: missing `--` separator. Use:\n"
                "    tellonce_codex exec [--project-root PATH] [--timeout SEC] -- <wrapped command...>\n"
                "Without `--`, tellonce_codex flags can intercept arguments meant for the wrapped command.",
                file=sys.stderr,
            )
            return 2
        if not cmd:
            print("exec: no command given after `--`", file=sys.stderr)
            return 2
        state = ensure_registered(project_root).state_root
        result = run_wrapped(state, cmd, timeout_s=args.timeout)
        return result.exit_code
    return 0
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall