cthulhu/AGENTS.md

AGENTS.md (Codex CLI guidance)

This repository is a screen reader. Prioritize accessibility, correctness, and stability over “clever” changes.

System interactions

• If a command requires sudo, stop and ask the user to run it (no password entry is possible from here).

Build / run quick refs

• Local dev build + install: ./build-local.sh
• Quick local sanity checks: ./test-local.sh
• Clean local artifacts/install: ./clean-local.sh
• Meson (manual):
  • meson setup _build --prefix=$HOME/.local
  • meson compile -C _build
  • meson install -C _build

Runtime target and testing rules

• Make source changes in this repo, not in ~/.local/lib/python*/site-packages/cthulhu/, unless the user explicitly asks for an installed-package hotfix.
• If you confirm the active import comes from ~/.local/..., that does not mean you should edit there. It means you should update the repo and then run ./build-local.sh to replace the installed copy for testing.
• Default test/apply workflow for local Cthulhu fixes:
  • edit repo files
  • run ./build-local.sh
  • reproduce/test against the refreshed ~/.local install
• If repo and installed behavior differ, prefer rebuilding with ./build-local.sh over patching the installed package directly.
• Treat direct edits under ~/.local/.../cthulhu/ as an exception path that requires explicit user approval.

Coding guidelines

• When modifying existing code: follow the surrounding code’s conventions.
• When writing new code from scratch: prefer
  • variables: camelCase
  • functions/methods: snake_case
  • classes: PascalCase
• Keep changes clean and well-structured; avoid layering short-term workarounds when a focused fix is possible.
• Add debug logs where helpful for troubleshooting. When adding timestamps to logs, use: "Message [timestamp]" (message first).

Accessibility requirements (high priority)

General

• Screen-reader-first UX: assume non-visual navigation.
• No keyboard traps; Tab/Shift+Tab must move through all controls.
• Use clear, complete labels (e.g., “Confirm Password”, not “Confirm”).
• No Speech-Dispatcher usage in GUI apps (no spd-say); rely on the accessibility API.

Python GTK (Gtk 3)

• Associate labels with controls (mnemonics + buddy widget):
  • label.set_use_underline(True)
  • label.set_mnemonic_widget(entry)
• For Gtk.TextView, call set_accepts_tab(False) so Tab moves focus.
• For custom widgets, set accessible name/role via ATK where applicable.

PySide6 / Qt

• Set setAccessibleName() on all widgets.
• Associate labels via setBuddy().
• Use setAccessibleDescription() when extra context is needed.

Shell script rules

• Bash variables must be camelCase (except system env vars like ACCESSIBILITY_ENABLED).
• If you edit a #!/usr/bin/env bash, #!/bin/bash, or POSIX sh script, run shellcheck and fix issues.
• Avoid colorized output unless explicitly requested (accessibility-first; keep scripts simple).

Python Rules

• When making changes to the codebase, you must run ruff check and fix all problems therein.
• Additionally, you must run ty check and must fix all errors therein.

Plugins (Cthulhu)

• System plugins live in src/cthulhu/plugins/.
• Follow existing plugin patterns (keybinding registration, GTK dialog/window patterns, debug logging).
• Ensure plugin install integration is wired via Meson (src/cthulhu/plugins/meson.build + plugin subdir meson.build).

Meson install reminder (important)

• If you add new Python modules under src/cthulhu/, update src/cthulhu/meson.build so they get installed (otherwise imports can fail after install).
• If you add a new plugin directory, update src/cthulhu/plugins/meson.build and add a meson.build in the plugin directory.

Common Cthulhu agent mistakes

• Checking the import origin, seeing ~/.local/..., and then editing the installed package instead of the repo.
• Forgetting that ./build-local.sh is the normal way to apply repo changes into the installed copy for testing.
• Making repo fixes and then diagnosing the old installed copy without rebuilding.