Plugins — Ablative docs

Install in Claude Code

From the root of a Lys repository checkout, add the local marketplace and install the plugin:

claude plugin marketplace add ./
claude plugin install lys@lys-local

The marketplace is lys-local; its Claude Code package is plugin/. Inspect the connection before consent:

claude mcp list

plugin:lys:lys: https://lys.ablative.com.au/api/mcp (HTTP) - ! Needs authentication

Open a new host session, open /mcp, choose the Lys server and Authenticate, then complete the Lys consent screen. Run /lys:setup to read the tool list and the caller’s admitted discovery.

Claude Code skills

access: Give, inspect and explain Lys access through grants, roles, requests and reviews.
agents: Manage Lys agent profiles, harnesses, skills, budgets, certificates and launches.
apps: Manage Lys apps, schema registration, approvals, placements and OAuth connections.
draft-workflow: Record, inspect and decide Lys directory and product drafts without confusing approval with execution.
goals: Manage Lys goals, alarms and scheduled delivery with occurrence evidence.
identity: Read and manage Lys identities, own agents, accounts and sessions.
lys: Operate Lys through its four MCP tools, live schemas, grants and named refusals. Use before Lys route work.
network: Read Lys computers, runners, client artifacts and join evidence.
runtime: Operate Lys seats and runtime sessions with delivery receipts and event signals.
secrets: Manage Lys secret metadata and handle scope without revealing secret values.
service: Inspect Lys service contracts, health, configuration, receipts, setup and change signals.
teams: Manage Lys team membership, nesting and the caller-visible team tree.
words: Read, preview and revise Lys instruction slots and named templates.

Claude Code commands

/lys:capabilities: Show the routes, resources and actions this Lys connection currently holds.
/lys:drafts: List, prepare or decide Lys drafts through the correct draft family and responsible authority.
/lys:give-access: Prepare and apply an authorized Lys grant, then verify its receipt and recipient access.
/lys:my-agents: List the agents visible to the current Lys caller, with honest authentication limits.
/lys:read-route: Read a declared Lys route using its current schema and the caller's authority.
/lys:setup: Verify the Lys plugin connection, live tool list and admitted discovery without changing state.
/lys:whoami: Identify the caller of this Lys connection without confusing a person and an agent.

Install in Codex

From the same repository root, add the Codex marketplace and plugin:

codex plugin marketplace add ./
codex plugin add lys@lys-local

The Codex marketplace manifest is .agents/plugins/marketplace.json; it selects plugins/lys/.

Claude Code: Lys version 0.1.0, enabled.
Codex: Lys version 0.1.0, enabled.

Inspect the server’s authentication state:

codex mcp list

Server: lys
URL: https://lys.ablative.com.au/api/mcp
Auth: Not logged in

Begin login and complete the person’s consent at Lys:

codex mcp login lys

In a new session, invoke the Lys setup skill. Use the skill picker when another plugin has the same short name.

Codex skills

access: Give, inspect and explain Lys access through grants, roles, requests and reviews.
agents: Manage Lys agent profiles, harnesses, skills, budgets, certificates and launches.
apps: Manage Lys apps, schema registration, approvals, placements and OAuth connections.
capabilities: Show the routes, resources and actions this Lys connection currently holds.
draft-workflow: Record, inspect and decide Lys directory and product drafts without confusing approval with execution.
drafts: List, prepare or decide Lys drafts through the correct draft family and responsible authority.
give-access: Prepare and apply an authorized Lys grant, then verify its receipt and recipient access.
goals: Manage Lys goals, alarms and scheduled delivery with occurrence evidence.
identity: Read and manage Lys identities, own agents, accounts and sessions.
lys: Operate Lys through its four MCP tools, live schemas, grants and named refusals. Use before Lys route work.
my-agents: List the agents visible to the current Lys caller, with honest authentication limits.
network: Read Lys computers, runners, client artifacts and join evidence.
read-route: Read a declared Lys route using its current schema and the caller's authority.
runtime: Operate Lys seats and runtime sessions with delivery receipts and event signals.
secrets: Manage Lys secret metadata and handle scope without revealing secret values.
service: Inspect Lys service contracts, health, configuration, receipts, setup and change signals.
setup: Verify the Lys plugin connection, live tool list and admitted discovery without changing state.
teams: Manage Lys team membership, nesting and the caller-visible team tree.
whoami: Identify the caller of this Lys connection without confusing a person and an agent.
words: Read, preview and revise Lys instruction slots and named templates.

The Claude Code command workflows are skills in the Codex package; it has no separate command directory.

Connect the MCP server

Both manifests select config/lys-mcp.json, which declares an HTTP server at https://lys.ablative.com.au/api/mcp. The host owns OAuth and the consent flow. This plugin needs no local Lys executable, SSH access, private signing key or manually supplied bearer token.

Transport: Streamable HTTP to https://lys.ablative.com.au/api/mcp, declared in config/lys-mcp.json for both hosts.
Authentication: Host-managed OAuth and Lys consent. Codex requests authentication on install; Claude Code offers Authenticate in /mcp.
Caller: An app agent answering to the consenting person. Product grants belong to that agent; consent does not copy the person’s rights.
Discovery: Read what-can-I-do and the live OpenAPI before assembling route bodies. Discovery remains subject to the caller’s admitted scope.
Local bridge: lys mcp is a separate signed bridge for a numeric loopback HTTP URL. It is not the launcher for this remote HTTPS plugin.

Tools returned by tools/list

what-can-I-do: List the routes, resources and actions this connection may reach under its live grants.
read: Read through an existing HTTP route with the caller's credentials and admission.
change: Change through an existing HTTP route. Its validation, authority checks and refusals apply unchanged.
drafts: Ask an existing draft route with the caller's credentials. This transport grants no draft authority.

On an admitted connection, what-can-I-do returns routes and live grants. Read the current operation schema before supplying a route or body. MCP describes the inputs and the separate signed local bridge.

Keep the caller’s authority explicit

The OAuth connection is an app agent. Personal routes and directory draft decisions require a person connection; consenting does not let the app agent impersonate that person. Directory draft creation requires an agent signature, which the HTTP plugin does not supply. Use a correctly authenticated connection for that operation.

The drafts tool is restricted to directory /drafts routes. Product drafts use /product-drafts through read or change. Approval and execution are separate results; keep the receipt for each.

Answer a refusal

NotSignedIn: Exact refusal reason: NotSignedIn: sign in through the configured issuer first. Complete host authentication before asking for discovery.

{"refusal":"NotSignedIn","reason":"NotSignedIn: sign in through the configured issuer first","fields":[]}

An unauthenticated POST to /api/mcp receives status 401 and the authentication metadata challenge:

www-authenticate: Bearer resource_metadata="https://lys.ablative.com.au/.well-known/oauth-protected-resource"

Complete host authentication through the intended connection. Preserve an uncertain operation’s identifier and reconcile it before attempting another change.

Companion roles

Claude Code includes access-reader and draft-preparer. They read authority and prepare proposed drafts within the caller’s grants. The Codex package supplies lys-access-reader and lys-draft-preparer companion role files; its plugin manifest does not register them automatically.