Couch agents

Shared agents, skills, and local tools for developing Couch, the Linux distribution for the Sanytron Astrion HA100 remote. Use this repository as the home for new development agents, repeatable workflows, and improvements learned while working on Couch.

Get started

Requires Python 3.11+, Git, and a Codex release supporting project custom agents. The setup was checked with Codex CLI 0.154.0. Build dependencies are needed only when working on the relevant Couch subsystem.

git clone https://github.com/dangerouslaser/couch-agents.git
git clone --branch dev https://github.com/dangerouslaser/couch.git  # if needed
cd couch-agents
python3 scripts/couch_tools.py doctor --repo ../couch
python3 scripts/couch_tools.py install --repo ../couch

Open a new Codex session in the Couch checkout. The installer links individual agents into .codex/agents/ and skills into .agents/skills/, and locally excludes those links from Git. It preserves existing configuration and refuses conflicting files. It does not change global settings, install dependencies, contact a device, or make model calls. Keep this clone in place while installed.

Try:

• “Use $couch-integration to add this receiver following the current client SDK.”
• “Use $couch-kernel to investigate the display regression and prepare a reproducible build.”
• “Use $couch-base-os to fix Wi-Fi trial rollback after a service restart.”
• “Use couch-review as a subagent to review this diff against dev.”

Skills can guide the current agent; custom roles are available when requesting subagents. Each developer retains their model and permission settings. Other coding assistants can read the SKILL.md workflows and invoke the same CLI tools directly.

Included roles

Agent / skill	Scope
couch-integration	DeviceClient SDK, capabilities, credentials, broker and full provider registration
couch-kernel	Separate kernel source, HA100 recipes, provenance and device acceptance planning
couch-base-os	Alpine boot, stage2, system service, recovery, Wi-Fi/SSH and runtime rollback
couch-ui	Slint panel and web configuration, shared model/API behavior and previews
couch-release	Runtime/installer inventory, source and license closure, release preparation
couch-review	Read-only review of protocol, service, boot and hardware risks

Tools

Run from this repository; every Couch operation requires an explicit checkout path.

python3 scripts/couch_tools.py context --repo ../couch --area integration
python3 scripts/couch_tools.py plan --repo ../couch --area base-os
python3 scripts/couch_tools.py check --repo ../couch --area kernel          # preview only
python3 scripts/couch_tools.py check --repo ../couch --area kernel --run    # host tests
python3 scripts/couch_tools.py uninstall --repo ../couch

context reports the checkout revision and relevant document paths without reading local configuration or secrets. doctor reports tools and Rust targets. plan emits conservative host validation commands. check --run executes those commands, stops on the first failure, and returns nonzero for failures, missing tools, or timeouts; remaining steps are reported as not run. Narrow a printed plan to the affected workspace when appropriate. Existing formatting failures must not trigger unrelated rewrites.

Uninstall removes only links owned by this clone; harmless local Git exclude entries remain. Update with a reviewed git pull --ff-only, rerun install to discover newly added roles, and restart Codex. Do not install the same skills both as project links and through another plugin mechanism.

Build more agents here

See CONTRIBUTING.md for the tested new-agent generator, architecture for boundaries and installation, and documentation reviewed for Couch and Codex SDK references. The plugins/couch-dev directory is a validated skill-only Codex plugin package; the clone installer above also installs custom agent roles, which are maintained separately from plugin skills.

python3 scripts/validate.py
python3 -m unittest discover -s tests -v

CI runs these on Linux and macOS with Python 3.11 and 3.14. Behavioral scenarios are manual acceptance cases; CI does not claim model quality or hardware acceptance.

Couch's checked-out documentation takes precedence over this kit. Host checks and cross-compilation do not prove physical behavior. Never write preloader_* or lk; consult current recovery procedures before device writes. Credentials, backups and calibration stay outside Git.

Licensed under GPL-3.0, consistent with Couch.