Integrations and extension points

Screph is extended through data, adapters, profiles and internal registries, but it is not currently a platform for installing arbitrary third-party plugins. This page separates supported user-facing integration points from mechanisms that still require source changes.

What you can use now

Surface	Status	Contract
Canonical project / derived JSON	Implemented	Versioned JSON schemas for projects, `for_ai_agent`, tree modules and CV manifests. External consumers read files, not internal Qt state.
Automation Python API	Implemented	`automation_runtime` loads a project, finds images or text and performs explicit input actions.
LLM / speech connections	Implemented	Configurable profiles for supported providers, local runtimes and a custom OpenAI-compatible endpoint. This is a configuration surface, not a Python plugin loader.
Semantic rules catalog	Implemented	The Semantics tab accepts an external JSON catalog path. The file is validated; `selection_semantics.rule_catalog_load_failed` blocks the semantic command path instead of silently falling back.
Custom YOLO weights	Implemented	A custom `.pt` file can be imported. The file remains on disk, but its custom registry entry currently exists only for the running process.

What “plugin” means inside the codebase

The codebase contains an InspectionPluginRegistry and TimelinePluginHost, plus registries for CV methods, Assistant actions, settings providers and semantic handlers. They provide typed composition boundaries between internal components and are covered by tests, but they are assembled by the application itself.

Not a public plugin platform

There is currently no Python-entry-point discovery, plugin manifest or package format, install/uninstall UI, compatibility negotiation for third-party packages or sandbox. A class named *PluginRegistry does not by itself mean that users can install an external module.

Adding a CV method, timeline track, evidence inspector, settings provider or Assistant action is currently a development task: code is wired into a composition root, given a typed contract and tests, and then included in a build.

Built-in IDE/codegen extension loader

On first use, ide_interaction.extensions scans only subpackages inside the installed package, imports each entry.py, and caches the list for the life of the process. This is an internal composition loader: it does not scan a user directory, Python entry points or downloaded packages, and it does not validate a manifest, signature or compatibility.

Built-in package	Actual status	Consumer
AutoHotkey, Robot Framework Visual, SikuliX, TagUI, UiPath CV	Internal scaffold	Their current `entry.py` files return `None`, empty lists and empty context. They add no mode, backend, target profile or runner and must not be treated as available integrations.

Failure boundary. If importing an entry raises any ModuleNotFoundError, the loader currently skips the package silently; other exceptions are logged. A missing built-in adapter may therefore indicate a missing module, and the UI is not a complete diagnostic report.

Launcher CLI and the headless boundary

pyproject.toml publishes one Python console entry point, Screph = main:main. The installer instead creates shortcuts to <selected TargetDir>\screph.exe --mode prod; the default target is %LOCALAPPDATA%\Screph. It does not add a Screph command to PATH. Both entry points launch the complete program or one of its process surfaces; this is not a headless CLI for editing projects or running arbitrary automation.

& "$env:LOCALAPPDATA\Screph\screph.exe" --help
& "$env:LOCALAPPDATA\Screph\screph.exe" --mode prod --verbose
python main.py --mode dev
python main.py --mode prod --log-file C:\logs\screph.log

Argument	Actual behavior	Boundary
`--mode dev\|prod`	Sets a complete group of runtime environment values. The packaged default is `prod`; the source default is `dev`.	`dev` requires a source/development checkout with `WebSite/local_dev`, its certificate and website Python environment; it is not an embedded production web host.
`--verbose`, `--log-file`	Change logging for the current process; an explicit file does not become the persisted user default.	Use an absolute path for a predictable destination.
`--config-dir`	Sets `SCREPH_CONFIG_DIR` before the settings runtime is created.	Despite its name, it redirects the entire root used by `get_runtime_file(...)`: settings, logs, caches, models and other runtime data. Projects at explicitly selected paths and secrets in Windows Credential Manager do not move there.
`--server-only`	Only with `--mode dev`: checks health, starts local HTTPS through PowerShell if necessary, waits up to 15 seconds and exits the launcher.	The launcher does not remain as the foreground owner of the server loop; lifecycle belongs to `start_https.ps1`, `restart_https.ps1` and the PID file.
`--codegen-gui`	Launches the standalone Screph Code window instead of the main desktop window.	The corresponding component, runtime and LLM configuration are required.
`--profile-startup`	Enables `cProfile` before Application construction but disables it only after `app.run()` exits, then prints 50 cumulative entries.	The name is narrower than the actual boundary: it profiles the complete GUI session until exit, not startup alone.
`--oauth-callback`, `--pro-agent`	A specialized custom-URI completion path and internal JSON-RPC over stdin/stdout.	These are integration and process contracts, not interactive user commands. Normal account device login starts in the UI, and a Pro Agent consumer should launch its process.

What the packaged candidate confirms

The inspected main.dist/screph.exe is an AMD64 PE32+ binary with the CUI subsystem; --help actually prints the listed visible flags and the prod default. Launching the current candidate from a shortcut may therefore include a console window: this is the current Alpha packaging boundary, not a separate headless product.

A positional project.json is not an Open Project command. Open projects through the GUI and Project Manager.
The current source launcher now exits with code 2 for unknown arguments before starting the GUI; the already-built candidate still uses the earlier parse_known_args contract and may continue silently after a typo.
Hidden smoke and runtime-dependency flags serve packaging, the installer bridge and diagnostics. They are not a stable public CLI.
For headless screen actions, use the separate automation_runtime script and API contract; the Screph launcher does not accept an arbitrary automation script.

Website HTTP API

The current versioned API covers health, profile and balance, usage, diagnostics upload and speech inference; separate user-management routes cover login, device authorization and support. It does not expose generic remote CRUD for Screph projects, project-package upload or desktop automation execution.

Auth, server speech and data transfer →

Choose a durable boundary

For custom analysis, use canonical or derived JSON and check schema_version.
For screen actions, use automation_runtime and its explicit target/input contract.
For a model, use a connection profile or supported custom endpoint rather than importing UI internals.
For a new built-in capability, work through the source and its registry contract; do not load untrusted Python as a “plugin.”

For formats and examples, see data and exports. For source contributions, see community and contributing.

Unclear

Future external plugin system

Architecture documents call for versioned IPC and plugin boundaries between selected components, but the repository does not confirm a user marketplace, general SDK or delivery date for third-party plugin installation. It therefore cannot be promised as a Planned feature until a public contract and roadmap exist.