allye-pi

Allye keeps your projects, epics, specs and tasks on the server. This plugin connects your coding agent to it:

• Allye MCP (https://mcp.allye.app/mcp, OAuth 2.1) — projects, epics, specs, tasks and team tools, plus context, memory and your organization's skills.
• Bridge (/bridge <mode>) — a skill that designs specs with you and drives an approved spec to a reviewed branch and, with your approval, one PR, through a crew of specialized agents with security and review gates.
• Bootstrap — a short session-start note telling the agent that the MCP and Bridge are available, that the team follows the project (identified with project_resolve), and that a default team is only needed to create projects and for memory, todo and doc calls without a team_id.

Create a free Allye account →

Bridge modes

Supported harnesses

Every harness uses one server named allye. Tenant selection happens during OAuth consent; the harness owns client registration, token storage and refresh.

Claude Code

/plugin marketplace add allye-app/allye-plugin
/plugin install allye
/reload-plugins

Then open /plugin, find the Allye MCP server, click Connect and sign in. Update with /plugin update allye and /reload-plugins.

Pinned preferences at session start (Claude Code only, optional)

Pair this install with your Allye account and every new, cleared or compacted session starts with the preferences you pinned in Allye, shown to the agent as quoted data, not instructions. Pairing is a second SessionStart hook, separate from the offline bootstrap hook.

/allye:hooks pair      # connects this install to your account
/allye:hooks unpair    # deletes the local credential, no network call

• What it does. pair creates a random secret on your machine, asks the Allye MCP (through your existing OAuth connection) for a one-time pairing code, and exchanges the code for a hook credential. It prints Paired <device> as <email> in <organization>: check that the account and organization are yours. A rule that allows every Allye MCP tool also approves the pairing call without a prompt, so that check is your only gate. If they are not yours, run unpair and revoke the device.
• What leaves the machine. Only the device name, the client kind (claude-code), a challenge (a hash of the secret), the pairing code and, on each session start, the credential as an authorization header. Never repository, file, conversation or environment content.
• Where the credential lives. ${CLAUDE_PLUGIN_DATA}/hook-credential.json (~/.claude/plugins/data/<plugin id>/), mode 0600 in a 0700 directory. Claude Code removes it when the plugin is uninstalled from its last place. To keep the agent from reading it, add Read(~/.claude/plugins/data/allye*/hook-credential.json) (adjust to your plugin data directory) to permissions.deny in your user-level ~/.claude/settings.json.
• Supported API origins. pair uses https://api.allye.app. ALLYE_API_URL is accepted only as https://api.allye.app, https://api.zeta.allye.app (HML) or http://localhost:<port> / http://127.0.0.1:<port> (local development).
• Session start. The hook makes one short request and prints the preferences, or one hint line when the credential is rejected, unsafe or the account is inactive. It is silent when you are not paired, offline or the API is unavailable. It needs curl and jq.
• Before uninstalling. Run /allye:hooks unpair, then revoke the device in Allye → Settings → Devices; unpair only deletes local files, so the credential keeps working on the server until revoked. Pair again before the expiry date shown at pairing.

Live session reporting (Claude Code only, optional)

When paired, hooks send Allye the state of your sessions (started, working, waiting, idle, ended), the tool names in use (within about 2 seconds of the call), subagent ids and types with their outcome, the spec and task keys the session is bound to and, on by default, short texts the agent wrote, each at most 140 characters: the description of a subagent dispatch, an activity phrase for each tool call (the description of a Bash or Agent call, else a fixed phrase such as "Read tree.ts" or "Run vitest" that holds at most one file name or Allye key and nothing else of the call. Without an agent-written description, Live sends only a fixed phrase from a short list: git actions (Commit to git, Push to git, Merge in git, Fetch from git, Read the history), pull request actions (Open the PR, Merge the PR, Check the PR), Check the heavy lock, Update the mission log, Search the code, Find . files (or Find files), Send a message, Save a memory, Update task (or Update a task), the test, lint, build and diff phrases such as Run tests or Check git status, and Run a command for anything else (any pipe, redirect, chain with an unknown part or long command); no argument, branch, remote, message, path or flag value of a command is ever sent. The task key a subagent passes to its own task_start can label its step (a display hint).), the summary: line of a crew report, and a session label (at most 60 characters: the ALLYE_SESSION_LABEL variable or the title Claude Code gives the session) with the name of the working folder. A crew report is also read from the subagent transcript when the final message has none (only its whole-line fields leave, never the transcript). Small numbers and keywords from the report (attempt, next step, gate, checks, finding counts, phase, ready/approved) and the pull request number from the - PR: #N line of the mission log go with them. Paths, URLs, emails, IP addresses, secrets and backticked code are stripped on your machine on a best-effort basis, with no guarantee, and Allye scrubs them again (the Allye scrub is the authoritative one); /allye:hooks live activity off turns the texts off (so does Detailed Live in the Allye app). Only you can see these texts in Allye (a teammate's token receives none). Allye keeps them for 30 days with the run: the three texts, the session labels, up to 50 activity phrases per step and the working folder name; turning Detailed Live off deletes them. A small background watcher (one per session, no network use while Claude Code runs) ends the run on Allye when Claude Code is closed without a normal exit. Through the Allye MCP, task_start, task_submit, spec_context and spec_get (and a /bridge launch with a key) tie a session to a spec or task. The subagent type, tool names, the texts and allye:<action> / spec / task keys DO leave your machine; prompts, commands, tool inputs and outputs, file paths, notification messages, assistant messages other than the report's whole-line fields, transcripts, branch names and credentials never do. The name of the working folder (one path component, never the path) leaves only with a session label, and not when its name looks secret. Update the plugin only after the Allye API that accepts the new fields is live. Control it with /allye:hooks live off|on|status; events, fields, the watcher and local files are in docs/live-reporting.md.

Answering from Allye (Claude Code only, optional)

With Live reporting on, a blocking PermissionRequest hook (hooks/live-answer.sh, timeout 120 s) lets you answer a question (AskUserQuestion) or answer a permission from Allye, with the same options the terminal shows as far as a hook can reproduce them, while the dialog is open. The terminal always keeps the last word (the dialog stays usable while the hook waits) and on any doubt the hook exits with no output. Options (seven fixed ids with fixed labels): allow_once "Yes", allow_edits_session "Yes, allow all edits this session", allow_session "Yes, allow for this session", allow_folder "Yes, allow this folder", allow_always "Yes, always allow" (saved in a settings file, it outlives the session), switch_auto "Yes, switch to auto mode" (only Bash, in the default and acceptEdits modes) and deny "No". allow_once and deny are always offered; the others only when the hook can reproduce them for that call, and when the terminal shows something it does not offer (an unmapped rule, the option for a protected .claude folder, a folder it refuses) the request is flagged options_partial, so Allye knows the terminal shows more than it offers. allow_folder is never offered for /, your home folder or their ancestors. Rules stay on your machine: the rule text, directories and modes Claude Code suggests are held in memory only and are rebuilt into the answer of the option you chose; Allye can only pick one of the ids the hook offered (plus a cleaned deny message), never supply a rule. Risk (Bash, protected paths such as dotfiles, scripts/, manifests, lockfiles and CI files, paths outside CLAUDE_PROJECT_DIR or all path tools when it is unset, any Allye MCP write, other MCP or unknown tools) is still computed and shown, but no longer limits what you can choose. Allye asks for a fresh password or MFA (valid for 300 s) for every allow except allow_once at normal risk; the API enforces it and the app prompts, outside the hook. Tools on a short denied list (ExitPlanMode) and unknown tools get no phrase and are answered in the terminal; with texts off (Detailed Live or live activity off) no options are sent and only the legacy allow once at normal risk, or deny, applies. A repository .mcp.json server named plugin_allye_allye cannot be told from the plugin's by name (known limit; the API keeps any higher risk it computes). What leaves the machine, per request: the session hash, the kind, a hash of tool name and input (SHA-256 of jq -S -c over [tool_name, tool_input]; for a question, over its questions), the risk class, the tool name (other MCP servers as mcp), the cleaned activity phrase (a fixed phrase such as "Use a tool" for other MCP tools, WebFetch and the tools with an option proven), for a permission the option ids with their fixed labels and options_partial, for a question its cleaned texts (none is sent, and no question is opened, when Detailed Live is off) and the reporter's last seq; the reporter also sends the call id tu and, when a call ends, cmd_end {tu, h, seq, at, ok}. Never the raw command, path, prompt, tool input, rule text, directory, suggestion entry, mode or destination. The wait is up to 110 s (hook timeout 120 s); it stops at once when Allye reports the request terminal, expired or not answerable, cancels the request on exit while pending, and after an answer in the terminal keeps waiting until Allye ends the request or the 110 s pass. /allye:hooks live off (also unpaired, no credential or an unusable origin) stops the events and cmd_end, and the hook exits at once with no network call; the origin comes only from the pairing file; after a failed open it pauses 60 s (10 minutes after a 404 or 405). Spike verdict VERDICT: permission=go question=go (questions use the PermissionRequest decision updatedInput.answers; a PreToolUse hook shows no dialog): docs/spikes/live-return-channel.md; check it with node --test test/test-spike-doc.mjs (or npm run test:hooks-config); a real rerun needs an interactive Claude Code session. Known limits: decision texts get NFC only when uconv is installed, length caps count code points, the hook tests use GNU tools and there is no CI for them yet; update the plugin only after the Allye API that accepts the new fields is live (releases happen on merge to main, API first). Details in docs/live-reporting.md.

Codex, OpenCode

Paste into the agent. The install and update guides install one pinned release: the latest GitHub release unless you name a version. They check that it exists, never download from a branch, and keep a timestamped backup of any config they rewrite (opencode.json, ~/.codex/AGENTS.md, ~/.codex/skills/bridge*) under ~/.allye/backups/<harness>/.

Install Allye following: https://raw.githubusercontent.com/allye-app/allye-plugin/main/docs/install-codex.md
Install Allye following: https://raw.githubusercontent.com/allye-app/allye-plugin/main/docs/install-opencode.md

Pi, OMP

pi install npm:allye-pi@<version>          # Pi
omp plugin install allye-pi@<version>      # OMP

Use a pinned <version> (the guides resolve it for you). Then add the allye MCP server as described in install-pi.md or install-omp.md. In OMP, allye-pi shows one notice at session start with the exact command /mcp add allye --scope user --url https://mcp.allye.app/mcp --transport http when no allye server is found in OMP's own mcp.json files; it never writes configuration.

Your organization's skills

install.sh installs the skills your organization keeps in Allye's Skills section (per tenant and team) into a harness on your machine. It is not needed to install this plugin.

export ALLYE_PAT=pat_...                    # Allye → Settings → API
./install.sh list --scope team              # approved skills you can see
./install.sh install claude team-standards  # claude | codex | opencode | pi | omp
./install.sh install claude team-standards --reinstall   # replace an edited copy (kept as a backup)
./install.sh status                         # offline integrity check

Each install downloads the skill's approved release, verifies every file and the canonical hash, opens a distribution for this machine, verifies the API-signed execution token, publishes the files into the harness's user skills directory with a provenance sidecar, and records the result on the API. The API decides which runtimes may receive skills; the installer reports its decision rather than working around it. Requires bash, curl, jq and Node.js 18+. The installer speaks compatibility contract 1.1.0.

Until the allye-api PROD release that supports contract 1.1.0, the installer works only against HML (ALLYE_API_URL pointing at the HML API). Against PROD it fails with 409 RUNTIME_INCOMPATIBLE or an execution-context error about a missing signing key, and changes nothing.

Who can install, where skills go, how edited, deleted and moved copies are handled, and the API errors are in docs/org-skills.md.

Repository layout

bootstrap/allye.md          shared bootstrap text (single source; scripts/sync-bootstrap.sh copies it to manifests/codex/AGENTS.md)
skills/bridge/              the Bridge skill and its references
skills/bridge-*/            the crew skills (Armorer, Recon, Strategist, Architect, Dispatcher, Pilot, Navigator, Copilot, Medic, Optimizer, Shield, Watcher)
agents/bridge-*.md          native crew subagents (Claude Code; OpenCode registers them from here): load the crew skill under a per-role tool allowlist
hooks/                      Claude Code hooks (bootstrap, pinned preferences, Live reporter, blocking answer hook) and the script behind /allye:hooks
.claude-plugin/, .mcp.json  Claude Code plugin and marketplace manifests
manifests/                  Codex copy of the bootstrap (codex/AGENTS.md, synced) and a sample OpenCode config (opencode/)
packages/                   allye-opencode (OpenCode plugin) and allye-pi (Pi/OMP extension, root package.json), both on npm
install.sh, install/        organization skills installer and its tests
docs/                       per-harness install and update guides, organization skills details

Development

npm install
scripts/sync-bootstrap.sh   # after editing bootstrap/allye.md
npm test && npm run typecheck   # tests (offline): bootstrap, hooks (npm run test:hooks), crew agents, skills, installer and docs gate, Pi and OpenCode; then the Pi typecheck
cd packages/allye-opencode && bun install && bun run typecheck && bun run build

Releases

Releases are automated by semantic-release on every push to main (Conventional Commits). It bumps the version in .claude-plugin/plugin.json, .claude-plugin/marketplace.json, packages/allye-opencode/package.json, package.json and package-lock.json, updates CHANGELOG.md, tags and creates the GitHub release. CI then publishes allye-opencode and allye-pi to npm when their version changed. ./release.sh [major|minor|patch] is the manual fallback.

License

MIT, see LICENSE.