Osprey plugin
A Claude Code plugin and CLI for scientific facilities: an agent finds control channels, writes to hardware after approval.
- 83 ★ on the repository
- Last commit
- BSD-3-Clause
Broad access
Why this level
- The agent works with a facility control system and prepares hardware writes; each write needs human approval, but limits and rules come from the deployment.
- Model provider keys live in the deployment `.env`.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/ospreyDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent works with a facility control system and prepares hardware writes; each write needs human approval, but limits and rules come from the deployment.
- Model provider keys live in the deployment `.env`.
This is third-party code. Review the repository files before installing.
What it does
Osprey is a Python framework for agentic work with the control systems of scientific facilities such as particle accelerators. Claude Code acts as the agent, and the `osprey` plugin adds skills and MCP tools that break an operator request into auditable steps. The framework handles control-specific problems: semantic search across huge channel namespaces, connectors for different stacks (EPICS, DOOCS, TANGO and a Mock connector ship in-tree) and search across facility electronic logbooks. Every hardware write goes through pattern detection and channel boundary checks and needs human approval. The `/osprey:setup` skill builds a deployment repository in a guided conversation, with `profile.yml` as the source of truth.
Who it is for. Engineers and operators of scientific facilities who build an agent interface to their control system and refuse unsupervised hardware writes.
Good fit when
- A deployment has to be built for a particular detector, beamline or accelerator subsystem.
- An operator searches thousands of channel names by meaning and wants the agent to suggest the right one.
- Entries in the facility electronic logbook must be found for a given fault.
- A team checks its control scheme on the Mock connector before touching live hardware.
Not a fit when
- You want a ready tool for everyday software work: Osprey targets facility control systems.
- Hardware writes must run fully automatically, without operator confirmation.
- The control stack has no ready connector and nobody can write one.
Example request
Create an Osprey deployment for our beamline: walk me through setup and show which hardware writes will need my approval.Limitations
The framework is pre-release: public APIs may change between releases, so pin a version (CalVer, `vYYYY.M.P`) and read the changelog before upgrading. It needs Python 3.11 or newer and the `uv` manager; a deployment configures model providers through keys in `.env`. Only EPICS, DOOCS, TANGO and Mock connectors ship in-tree, other stacks connect through the connector interface. Write safety depends on the limits and rules you define in the facility data.
How to disable. Remove the plugin with `claude plugin uninstall osprey@osprey` and the CLI with `uv tool uninstall osprey-framework`. Delete the deployment repository and the `.env` with keys by hand.
FAQ
How do I install Osprey?
Run `uv tool install osprey-framework`. Pre-releases need the `--prerelease allow` flag. Then run `osprey init quickstart --preset hello-world`, `osprey build` and `osprey web`.
How do I add the plugin to Claude Code?
Add the source with `claude plugin marketplace add als-apg/osprey --sparse .claude-plugin plugins` and install `claude plugin install osprey@osprey`. Then type `/osprey:setup` in an empty folder.
Can the agent change hardware values on its own?
No. Pattern detection and channel boundary checks come first, then a person has to approve the write.
Which control systems does Osprey support?
EPICS, DOOCS, TANGO and Mock connectors ship in-tree. LabVIEW and other stacks connect through the connector interface.
Can I use a different model?
Yes. Claude Code stays the agent harness, and the model behind it is a configuration choice. The Claude Code specific code sits in one adapter.
Discussion
No questions or reviews yet.
Related
PluginsFour Claude Code plugins turn a manual procedure into steps run by code, with retry limits and a draft that never invents facts
A self-hosted control plane for running several agents: task dispatch, run review, spend tracking, connected via MCP, CLI or REST
A Codex plugin and MCP bridge to an app that records your computer work and turns it into a graph of steps for an agent
A plugin that makes Claude Code a background assistant: scheduled tasks, Telegram, Discord and Slack replies, a web dashboard.
A CLI that keeps Claude Code agents running around the clock in PTY sessions, steered from Telegram, a dashboard and cron.
Orchestrator for Claude Code, Codex and Gemini CLI: YAML workflows that loop until your own quality gates pass
README in short
The description is short: a quick start, a feature list and links to the documentation. Rights to the code belong to the University of California through Lawrence Berkeley National Laboratory.