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

shared_lib/_install_merge_settings.py

View on GitHub
#!/usr/bin/env python3
"""Install helper — merge tellonce hooks into <project>/.claude/settings.local.json.

Used by install.sh / uninstall.sh / doctor.sh.

Modes:
  --add: add hooks to settings (idempotent, additive, does not remove existing)
  --remove: remove tellonce hooks from settings (uninstall)
  --verify: list registered hooks (doctor)

Versioned backup — cp settings.local.json.v3_pre_pt_<ts>.json before editing.
Python merge (not jq) — portable, no module-load dependency.
"""
import argparse
import json
import os
import shutil
import sys
from datetime import datetime


for stream_name in ("stdout", "stderr"):
    stream = getattr(sys, stream_name, None)
    if hasattr(stream, "reconfigure"):
        try:
            stream.reconfigure(encoding="utf-8", errors="replace")
        except (OSError, ValueError):
            pass


# Hooks definition (name → (event, timeout, desc)).
# Order matches the README architecture diagram. NOTE: Claude Code runs the
# matching hooks of an event in PARALLEL — the registration order below is
# documentation/diagram order, not an execution guarantee, and no hook may
# assume an earlier sibling's output landed first. The README declared:
#
#   Stop chain: check-observation-log → deterministic-block → verify-compliance
#               → shadow-judge
#   UserPromptSubmit: memory-upsert, retrieve-inject, shadow-alert-inject
#
# Python 3.7+ dict preserves insertion order, so this dict literally drives the
# settings.local.json registration order.
PT_HOOKS = {
    # ── Stop chain (executed top to bottom) ─────────────────────────────
    'check-observation-log.sh': {
        'event': 'Stop',
        'timeout': 10,
        'desc': 'Iron Law: append-only obs log gate',
    },
    'memory-deterministic-block.sh': {
        'event': 'Stop',
        'timeout': 10,
        'desc': 'Deterministic hard-block gate',
    },
    'memory-verify-compliance.sh': {
        'event': 'Stop',
        'timeout': 5,
        'desc': 'Compliance and legacy-pending metrics (log-only)',
    },
    'memory-shadow-judge.sh': {
        'event': 'Stop',
        'timeout': 30,
        'desc': 'Shadow LLM judge (log-only)',
    },
    'memory-upsert-enqueue.sh': {
        'event': 'UserPromptSubmit',
        'timeout': 5,
        'desc': 'Non-blocking shared memory inbox enqueue',
    },
    # ── UserPromptSubmit chain ──────────────────────────────────────────
    'memory-retrieve-inject.sh': {
        # Must exceed the cli backend's own subprocess timeout
        # (B5_RETRIEVE_TIMEOUT, default 12s incl. claude -p cold start) or the
        # harness kills the hook before even the keyword fallback can answer.
        'event': 'UserPromptSubmit',
        'timeout': 15,
        'desc': 'Semantic/fingerprint memory retrieve',
    },
    'memory-shadow-alert-inject.sh': {
        'event': 'UserPromptSubmit',
        'timeout': 5,
        'desc': 'Soft inject from shadow alert',
    },
}
LEGACY_HOOKS = {
    'memory-pending-promote.sh',
    'memory-pending-inject.sh',
}


def _versioned_backup(settings_path: str) -> str:
    """Cp settings.local.json → settings.local.json.v3_pre_pt_<ts>.json. Returns backup path."""
    if not os.path.exists(settings_path):
        return ''
    ts = datetime.now().strftime('%Y%m%d-%H%M%S')
    # Uniquify beyond second resolution: uninstall runs two --remove passes
    # back-to-back; with ts-only names the second backup (already-stripped
    # settings) would overwrite the first (the real rollback anchor).
    backup = f'{settings_path}.v3_pre_pt_{ts}-{os.getpid()}.json'
    if os.path.exists(backup):
        backup = f'{settings_path}.v3_pre_pt_{ts}-{os.getpid()}b.json'
    shutil.copy2(settings_path, backup)
    return backup


def _load_settings(settings_path: str) -> dict:
    """Load settings.local.json (empty file / missing → default dict)."""
    if not os.path.exists(settings_path):
        # Fresh file: hooks only. Do NOT write a permissions block — 'auto'
        # is not a valid Claude Code defaultMode, and imposing any permission
        # mode is not this installer's business.
        return {'hooks': {}}
    try:
        with open(settings_path) as f:
            return json.load(f)
    except json.JSONDecodeError as e:
        print(f'❌ settings.local.json invalid JSON: {e}', file=sys.stderr)
        sys.exit(1)


def _save_settings(settings_path: str, data: dict):
    """Write back with pretty format."""
    os.makedirs(os.path.dirname(settings_path), exist_ok=True)
    with open(settings_path, 'w', encoding='utf-8') as f:
        json.dump(data, f, indent=2, ensure_ascii=False)
        f.write('\n')


def _find_registered_hook(settings: dict, event: str, command_path: str):
    """Return the registered hook dict for command_path under event, or None."""
    for entry in settings.get('hooks', {}).get(event, []):
        for h in entry.get('hooks', []):
            if h.get('command') == command_path:
                return h
    return None


def _hook_already_registered(settings: dict, event: str, command_path: str) -> bool:
    """Check whether a hook is already registered in settings.<event>[].hooks[]."""
    return _find_registered_hook(settings, event, command_path) is not None


def cmd_add(settings_path: str, hooks_dir: str):
    """Add PT hooks to settings.local.json (idempotent).

    The hook .sh files self-locate their skill lib via ${BASH_SOURCE[0]}, so
    hooks_dir may live anywhere (relocated clone, shared HOME, CI, container).
    The only correctness requirement is that the hook .sh files actually exist
    in hooks_dir — checked below.
    """
    missing = [h for h in PT_HOOKS if not os.path.isfile(os.path.join(hooks_dir, h))]
    if missing:
        print(
            f'⚠ {len(missing)} hook .sh file(s) not found: '
            f'{", ".join(missing[:3])}{"..." if len(missing) > 3 else ""}',
            file=sys.stderr,
        )
        print('  Registration succeeds but at runtime the Claude Code harness reports command not found.', file=sys.stderr)

    backup = _versioned_backup(settings_path)
    if backup:
        print(f'  versioned backup: {backup}')

    settings = _load_settings(settings_path)
    settings.setdefault('hooks', {})
    legacy_commands = {os.path.join(hooks_dir, h) for h in LEGACY_HOOKS}
    for event, chain in settings.get('hooks', {}).items():
        cleaned_chain = []
        for entry in chain:
            entry['hooks'] = [
                hook
                for hook in entry.get('hooks', [])
                if hook.get('command') not in legacy_commands
                and not any(
                    hook.get('command') == os.path.join(hooks_dir, name)
                    and event != info['event']
                    for name, info in PT_HOOKS.items()
                )
            ]
            if entry.get('_pt_managed') and not entry['hooks']:
                continue
            cleaned_chain.append(entry)
        settings['hooks'][event] = cleaned_chain

    # Create a dedicated PT entry per event (no matcher, so it always fires)
    # instead of writing into chain[0]. Previously we appended into the user's
    # first entry, which means if the user's entry[0] had a matcher (e.g. for
    # PreToolUse semantics), our hooks could end up scoped to that matcher. Stop /
    # UserPromptSubmit don't take matchers in the current Claude Code spec, so the
    # bug was latent — but a dedicated entry is safer across Claude Code versions
    # and easier to remove cleanly later.
    added = 0
    skipped = 0
    updated = 0
    for hook_name, info in PT_HOOKS.items():
        cmd = os.path.join(hooks_dir, hook_name)
        event = info['event']
        timeout = info['timeout']
        existing = _find_registered_hook(settings, event, cmd)
        if existing is not None:
            # Idempotent re-run / upgrade: refresh the timeout in place so fixes
            # to PT_HOOKS (e.g. retrieve 5s → 15s) actually reach existing
            # installs — otherwise "re-run install.sh to upgrade" silently keeps
            # stale values forever.
            if existing.get('timeout') != timeout:
                existing['timeout'] = timeout
                updated += 1
            else:
                skipped += 1
            continue
        chain = settings['hooks'].setdefault(event, [])
        # Find OUR entry (one we previously created) by sentinel marker.
        # Fall back to first entry-without-matcher if any, else create new.
        pt_entry = None
        for entry in chain:
            if entry.get('_pt_managed'):
                pt_entry = entry
                break
        if pt_entry is None:
            pt_entry = {'_pt_managed': True, 'hooks': []}
            chain.append(pt_entry)
        pt_entry.setdefault('hooks', []).append({
            'type': 'command',
            'command': cmd,
            'timeout': timeout,
        })
        added += 1
    _save_settings(settings_path, settings)
    print(f'  added {added} hooks, updated {updated}, skipped {skipped} (already registered)')


def cmd_remove(settings_path: str, hooks_dir: str):
    """Remove PT hooks from settings.local.json."""
    backup = _versioned_backup(settings_path)
    if backup:
        print(f'  versioned backup: {backup}')

    settings = _load_settings(settings_path)
    pt_commands = {
        os.path.join(hooks_dir, h)
        for h in set(PT_HOOKS) | LEGACY_HOOKS
    }

    removed = 0
    for event, chain in settings.get('hooks', {}).items():
        new_chain = []
        for entry in chain:
            new_hooks = []
            for h in entry.get('hooks', []):
                if h.get('command') in pt_commands:
                    removed += 1
                else:
                    new_hooks.append(h)
            entry['hooks'] = new_hooks
            # Drop entries we own (`_pt_managed`) once empty; keep user-owned
            # entries even if empty (user may want to re-fill them).
            if entry.get('_pt_managed') and not new_hooks:
                continue
            new_chain.append(entry)
        settings['hooks'][event] = new_chain
    _save_settings(settings_path, settings)
    print(f'  removed {removed} hooks')


def cmd_verify(settings_path: str, hooks_dir: str):
    """List PT hook registration status."""
    settings = _load_settings(settings_path)
    pt_commands = {os.path.join(hooks_dir, h): h for h in PT_HOOKS}

    found = {}
    for event, chain in settings.get('hooks', {}).items():
        for entry in chain:
            for h in entry.get('hooks', []):
                cmd = h.get('command', '')
                if cmd in pt_commands:
                    found[pt_commands[cmd]] = event

    print('Tellonce hook registration status:')
    print(f'  settings: {settings_path}')
    print(f'  hooks dir: {hooks_dir}')
    print()
    missing = []
    for hook_name, info in PT_HOOKS.items():
        if hook_name in found:
            print(f'  ✓ {hook_name} → {info["event"]}')
        else:
            print(f'  ✗ {hook_name} → MISSING (expected {info["event"]})')
            missing.append(hook_name)
    if missing:
        print(f'\n❌ {len(missing)} hooks not registered. Run install.sh.')
        sys.exit(1)
    print(f'\n✅ All {len(PT_HOOKS)} hooks registered.')


def main():
    parser = argparse.ArgumentParser(description='Merge tellonce hooks to settings.local.json')
    parser.add_argument('--settings', required=True, help='Path to .claude/settings.local.json')
    parser.add_argument('--hooks-dir', required=True, help='Path to .claude/hooks/ (where .sh wrappers live)')
    g = parser.add_mutually_exclusive_group(required=True)
    g.add_argument('--add', action='store_true', help='Add PT hooks (install)')
    g.add_argument('--remove', action='store_true', help='Remove PT hooks (uninstall)')
    g.add_argument('--verify', action='store_true', help='List PT hook registration status (doctor)')
    args = parser.parse_args()

    if args.add:
        cmd_add(args.settings, args.hooks_dir)
    elif args.remove:
        cmd_remove(args.settings, args.hooks_dir)
    elif args.verify:
        cmd_verify(args.settings, args.hooks_dir)


if __name__ == '__main__':
    main()
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