Connect Claude Code

Claude Code has the fullest Ony.ai integration: a real blocking gate. When Claude is about to run a risky action, Ony.ai holds it, phones you, and returns your keypad decision as allow or deny. When Claude asks a multiple-choice question, Ony.ai reads the options as a phone menu (with Claude’s recommended option flagged) and delivers your choice back as the answer.

Prerequisite: enroll the connector

Both install paths need the ony connector installed and enrolled on this machine. It provides the ony command the hook and skill call.

pip install ony
ony enroll --url <your-ony-url> --email <you>

You are prompted for the password; it is never accepted on the command line. Point --url at your own server (ony up runs one locally on SQLite) or at your hosted instance. New to Ony.ai? Start with the quickstart.

Path 1: the marketplace plugin

Inside Claude Code:

/plugin marketplace add ony-ai/ony
/plugin install ony@ony-ai

This installs the gate hooks and the ony skill. With the plugin, the skill is invoked as /ony:ony <mode> (the plugin namespace prefixes it).

Path 2: ony hooks install

Wire a specific project’s .claude/ directly, without the marketplace:

ony hooks install --project <repo>

This writes, into <repo>/.claude/:

• The /ony skill (a SKILL.md plus a dependency-free toggle script), invoked as /ony <mode>.
• A PermissionRequest gate hook - the interactive gate that rings exactly when Claude itself would stop and prompt you.
• A PreToolUse hook - carries multiple-choice questions, and the full pre-execution gate on headless installs (see below).
• Lifecycle hooks (SessionStart, UserPromptSubmit, Notification, Stop, SubagentStop) for session tracking and blockage detection. These forward event metadata only, never prompt text or transcripts.

Every hook entry carries a 600-second timeout so a slow phone decision is never cut off by Claude’s 60-second default.

One command from scratch

ony init run in a project does both steps at once: it enrolls this machine if needed, then wires the project exactly like ony hooks install. That is the path the quickstart uses.

Restart the session

Claude Code discovers project skills and hook wiring at startup. After either install path, restart your Claude Code session (or run /reload-plugins) so the /ony command loads.

Drive it with /ony

Set how Ony.ai should reach you. The skill is /ony <mode> (project install) or /ony:ony <mode> (marketplace plugin); you can also run ony <mode> from any terminal, and it takes effect on the next tool call.

Mode	Meaning
on	At the keyboard: phone me only for high-risk actions.
away	Remote control: phone me for every actionable step.
here	Back at the keyboard: return to high-risk-only calls.
off	Ony.ai does nothing; tool calls use normal permissions.
status	Show the current mode.

The mode is project-scoped: every session in the same project shares it, and other projects are unaffected. Full details, including how the gate composes with Claude Code’s permission modes, are on the modes page.

How the gate behaves

• Strictly passive reads (Read, Grep, Glob, LS) pass straight through. Everything else - Bash, file edits, MCP tools, web fetches, anything unknown - is treated as actionable, so Ony.ai raises a handoff for the risky ones.
• Risk is classified by the Ony.ai server. The client’s risk hint is never trusted, and approving is always done on the phone keypad, never by voice.
• Ony.ai composes with Claude Code’s own permission surface. It rings when Claude itself would stop and ask you - never for work you pre-authorized (allowlisted commands, accept-edits, bypass-permissions). away answers every such ask by phone; on answers only the high-risk ones and leaves the rest to the terminal dialog.
• Any hook failure defers to Claude’s normal prompt. The gate never hard-blocks the agent.

Headless (-p) mode

The interactive gate rides Claude Code’s PermissionRequest event, which does not fire in headless (claude -p) runs. If this project runs agents headless, opt into PreToolUse gating instead:

ony hooks install --project <repo> --headless

This records headless_gate in the project’s .ony/project.json so the PreToolUse hook takes the full pre-execution decision. Do not set --headless on an interactive install; it is only for headless projects.

Verify and troubleshoot

Run ony doctor to check the wiring end to end (enrollment, server reachability, signing, clock, carrier readiness, and the project’s hook install). If Ony.ai never calls or rings too often, see troubleshooting. To remove the wiring later, run ony hooks uninstall --project <repo>.