107 skills · 36 agents · 171 hooks

Quick Start
Why OrchestKit?
What You Get
Key Commands
Configuration
What OrchestKit observes
Install
FAQ
Development
What's New
Community

Quick Start

Pick the host you actually use. Claude Code is the full plugin (skills + agents + hooks). Cursor gets the same ork plugin minus Claude hook scripts. skills.sh is skills only — start with the 12 below, not the whole catalog.

Host support matrix

Measured 2026-09-08 on pi 0.85, Codex CLI and cursor-agent. Details, commands and the lane model: OrchestKit on pi, Codex and Cursor.

Surface	Claude Code	Cursor	Codex	pi
Skills (SKILL.md)	all	all, via the `ork` plugin	6 (`ork-codex` pack)	all via `pi install`, 78 auto-listed
Agents	all	all	4 role templates	none
Hooks	all	none	none	none
Rules	repo convention	14, plugin `rules` key	`AGENTS.md`	none
Commands	`/ork:<skill>`	36 wrappers	`$ork-<skill>`	`/skill:<name>`
MCP config	`.mcp.json`	`.cursor/mcp.json`	plugin `mcp.json`	`.pi/mcp.json`
Status	shipped	shipped	shipped	shipped

Claude Code

/plugin marketplace add yonatangross/orchestkit
/plugin install ork

Then /ork:setup. The wizard scans the repo, recommends skills, and writes MCP config.

CLI equivalent: claude install orchestkit/ork.

Cursor

Settings → Plugins / marketplaces → add yonatangross/orchestkit → enable ork → open a new chat. Same plugin Claude Code installs, not a five-skill fork. See Install → Cursor.

skills.sh (Cursor, Codex, OpenCode, …)

Starter 12 — doctor, setup, explore, implement, verify, review-pr, commit, expect, assess, brainstorm, create-pr, remember:

npx skills add yonatangross/orchestkit -s doctor -s setup -s explore -s implement -s verify -s review-pr -s commit -s expect -s assess -s brainstorm -s create-pr -s remember

The skill named implement is the implement workflow (/ork:implement in Claude Code). There is no ork-implement on the Claude plugin; Codex uses $ork-implement after the Codex pack is installed. Full catalog: npx skills add yonatangross/orchestkit (hundreds of SKILL.md files — do not treat that as unique users).

Why OrchestKit?

Every Claude Code session starts from zero. You explain your stack, patterns, preferences—again and again.

OrchestKit gives Claude persistent knowledge of production patterns that work automatically:

Without	With OrchestKit
"Use FastAPI with async SQLAlchemy 2.0..."	"Create an API endpoint" → Done right
"Remember cursor pagination, not offset..."	Agents know your patterns
"Don't commit to main branch..."	Hooks block bad commits
"Run tests before committing..."	`/ork:commit` runs tests for you

What You Get

One unified plugin, everything included.

Component	Details
107 Skills	RAG patterns, FastAPI, React 19, testing, security, database design, ML integration — loaded on-demand, zero overhead
36 Agents	Specialized personas (backend-architect, frontend-dev, security-auditor) — route tasks to the right expert
171 Hooks	Pre-commit checks, git protection, quality gates, browser safety — ship with confidence

All available in a single /plugin install ork. Skills load on-demand. Hooks work automatically.

Browse everything in the Docs →

Key Commands

/ork:auto         # Front door: describe a goal, it routes to the right skill
/ork:setup        # Personalized onboarding wizard
/ork:implement    # Full-stack implementation with parallel agents
/ork:expect       # Diff-aware AI browser testing
/ork:review-pr    # PR review with parallel agents
/ork:verify       # Multi-agent validation
/ork:commit       # Conventional commit with pre-checks
/ork:explore      # Analyze unfamiliar codebase
/ork:remember     # Save to persistent memory
/ork:doctor       # Health check

Configuration

/ork:setup detects your stack, recommends MCP servers, and writes the configuration for you.

Recommended MCP Servers

Server	Purpose	Required?
Context7	Up-to-date library docs	Prerequisite (22 of 36 agents grant its tools)
Memory	Knowledge graph persistence	Recommended
Sequential Thinking	Structured reasoning for subagents	Recommended
Tavily	Web search and extraction	Optional

Set "alwaysLoad": true on the first three in your .mcp.json. It skips the per-skill tool probe and shaves ~150ms off cold starts.

Context7 is a prerequisite, and ork does not ship it. 22 agents grant mcp__context7__* in their frontmatter, but .mcp.json is user-owned and project-scoped, so the grant refers to a server you add. Skip it and those agents answer from training data with no error raised. The recommended entry is the hosted HTTP server, which costs no local process:

"context7": {
  "type": "http",
  "url": "https://mcp.context7.com/mcp"
}

Free tier: 1,000 requests, public repos, no account. Context7 Pro ($10 per seat per month) raises that to 5,000 per seat and parses private repos; add "headers": { "Authorization": "Bearer ${CONTEXT7_API_KEY}" } and export the ctx7sk- key. Add the header only once the variable is exported: with it unset the unexpanded literal is sent as the token and every query fails, and it does not fall back to the anonymous free tier, so the keyless entry above is strictly better than a header with no key behind it. The legacy stdio transport (npx -y @upstash/[email protected]) is the fallback when the hosted endpoint is unreachable, but it spawns one child process per Claude Code session, so the fan-out scales with how many sessions you keep open.

Customizing skills

Skills install as files on your disk, but don't hand-edit the installed copy — it gets overwritten on update and silently diverges from the canonical playbook. The supported ways to extend (user-level skills, project skills, upstream PRs, or disabling a bundled skill) are in docs/extending-skills.md.

What OrchestKit observes

OrchestKit is a quality-gate plugin, so its hooks are the product rather than an add-on. This section states plainly what they see, where it goes, and how to turn each piece off.

Scope: broad and intentional. OrchestKit registers 171 hooks across 32 lifecycle events, including SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, and Stop. They are not gated to a particular framework or project type, because the gates they enforce (secret-write blocking, protected-file guards, git safety, file-size limits, agent status protocol) apply to any codebase. If you only want gates on some projects, enable the plugin per-project rather than globally.

Where data goes: a local file on your own disk.

What	Destination	Notes
Lifecycle events (session end, PR merged, goal converged, chain phase)	`~/.local/state/orchestkit/events.jsonl`	Written unconditionally, rotated at 10 MB. `ORK_EVENTS_LOG` redirects the path (used by the test suite)
Hook metrics: event name, tool name, payload size, duration	same local file	Size-capped metrics only
Prompt text and file contents	Never recorded	Hooks read them to make an allow/deny decision, then discard
Remote sync	Off	No endpoint is compiled in; see below

There is deliberately no global kill switch for the local write, because the gates depend on that state (the git-safety and chain-staleness hooks read their own prior events). To stop it entirely, disable the plugin. Individual noisy hooks have their own opt-outs: ORK_DISABLE_DEBT_TRACKER, ORK_DISABLE_WORKTREE_VERIFIER, ORK_DISABLE_COORDINATION_METRICS, ORK_NO_NOTIFY, ORK_NO_STALE_SWEEP, and ORCHESTKIT_SKIP_SLOW_HOOKS among others.

Network access is opt-in and unset by default. There is no hardcoded remote host anywhere in the shipped hook bundles (grep -o 'https\?://' plugins/ork/hooks/dist/*.mjs returns nothing). An outbound call happens only if you configure a destination yourself, via one of:

ORCHESTKIT_HOOK_URL + ORCHESTKIT_HOOK_TOKEN, which enable the manual hooks/bin/telemetry-sync.mjs CLI. It POSTs your local JSONL to your own endpoint. No hook ever invokes it; you run it by hand.
ORK_HQ_TELEMETRY_URL, which points the telemetry HTTP sink at your own collector.
ORK_HQ_TELEMETRY_USE_HQ_API=1 together with HQ_API_URL, the same sink aimed at a self-hosted HQ API.

The sink returns early when the URL or the token is missing, and telemetry-sync.mjs prints No ORCHESTKIT_HOOK_URL or TOKEN configured. Nothing to sync. then exits 0. There is no analytics ping, no crash reporter, and no feature-flag fetch.

What OrchestKit never reads. No OS keychain lookups, no ~/.aws/credentials, no SSH private keys, no browser cookie or login stores, no clipboard. The one place secret-shaped paths appear in the source is plugins/ork/hooks/dist/pretool.mjs, where id_rsa, .pem, .env, and credentials.json form a blocklist that stops Claude writing to them. That code denies access; it does not read those files.

Third-party MCP servers are recommendations, not bundled dependencies. The plugin ships no .mcp.json and declares no mcpServers. The table under Configuration is advisory, and /ork:setup asks before writing anything.

Install

/plugin install ork

No tiering. No version confusion. Just one powerful plugin.

Not on Claude Code? Pull a starter 12 into any agent (Cursor, Codex, OpenCode, …) via skills.sh — do not install the whole firehose on day one:

npx skills add yonatangross/orchestkit -s doctor -s setup -s explore -s implement -s verify -s review-pr -s commit -s expect -s assess -s brainstorm -s create-pr -s remember

All skills: npx skills add yonatangross/orchestkit. The implement skill is implement, not ork-implement.

Cursor

Cursor loads Agent Plugins and Cursor plugins. This repo already ships the Agent Plugins manifest at plugins/ork/plugin.json. Add the GitHub repo as a Cursor marketplace (Settings → yonatangross/orchestkit), enable ork, then open a new chat. That is the same plugin Claude Code installs, not a five-skill fork.

It also ships 14 rules under the plugin's rules key, generated from src/rules/ and src/shared/rules/. They are agent-fetched, so a rule costs context only when its description matches the task.

Claude hook scripts are not registered for Cursor: they depend on ${CLAUDE_PLUGIN_ROOT} (orchestkit#293, closed). Cursor enforcement for HQ repos stays in the consuming project's .cursor/hooks.json.

"Include third-party Plugins" can leak SKILL.md from ~/.claude/plugins. That is not an install. Proof is the ork plugin id plus the full skill catalog.

Codex

Codex uses its own plugin format, skill picker, and standalone role configuration. Add OrchestKit's Codex marketplace, then install the small portable workflow pack:

codex plugin marketplace add yonatangross/orchestkit --ref main --sparse .agents/plugins --sparse plugins/ork-codex
codex plugin add ork-codex@orchestkit-codex

Restart Codex after installation. Invoke a workflow explicitly with $ork-brainstorm, $ork-explore, $ork-implement, $ork-assess, $ork-verify, or $ork-review-pr; their narrow descriptions also let Codex select the relevant workflow automatically.

The plugin intentionally ships roles as templates because Codex loads custom roles from ~/.codex/agents/, not from a plugin manifest. From an OrchestKit checkout, run this one-time, non-overwriting install:

plugins/ork-codex/scripts/install-codex-roles.sh ~/.codex/agents

It installs ork_explorer, ork_implementer, ork_reviewer, and ork_verifier; restart Codex before spawning them.

Unattended runs: the `ork-mech` profile

For mechanical work (renames, bumps, codemods, sweeps that end in a diff), install the shipped profile and run codex exec against it:

plugins/ork-codex/scripts/install-codex-profile.sh ~/.codex
codex exec --profile ork-mech "<task>" </dev/null

The profile is a FILE, not a snippet you paste into config.toml. Measured on codex-cli 0.153.4: --profile <name> layers $CODEX_HOME/<name>.config.toml over the base config, and a legacy [profiles.<name>] table left inside config.toml makes the same flag a hard config-load error. The installer refuses to run next to that table, and refuses to overwrite a profile you already have.

What it sets, as codex exec prints it in its own header:

approval: never
sandbox: workspace-write [workdir, /tmp, $TMPDIR] (network access enabled)
reasoning effort: high

It deliberately does not pin a model (pass -m) and does not use --dangerously-bypass-approvals-and-sandbox, which drops the sandbox entirely. Two contracts a TOML file cannot express, so they stay on the command line:

</dev/null. codex exec reads stdin even when a prompt argument is given. An inherited open pipe blocks the run with Reading additional input from stdin... and no timeout.
--add-dir inside a git worktree. The writable roots are [workdir, /tmp, $TMPDIR]. A linked worktree's git common dir sits outside the workdir, so the first commit dies on index.lock. Add it:
```
codex exec --profile ork-mech \
  --add-dir "$(git rev-parse --path-format=absolute --git-common-dir)" \
  "<task>" </dev/null
```

Keeping the install current

ref main in the marketplace source is a cached snapshot, not a tracker. On the 2026-09-08 audit machine codex plugin list showed 10.0.0-beta.5 while main was three releases ahead. After an OrchestKit release, update and check:

codex plugin update
codex plugin list | grep ork-codex          # installed version
jq -r .version plugins/ork-codex/.codex-plugin/plugin.json   # what main ships

Documentation lookup (context7)

The plugin ships a context7 MCP server in its own manifest (mcpServers in .codex-plugin/plugin.json, defined in mcp.json), so installing the plugin registers it. Confirm with codex mcp get context7. It is scoped to the only two tools context7 exposes, resolve-library-id and query-docs, and it uses the hosted HTTP transport rather than an npx stdio child, so it costs no extra process per Codex session.

Export a key before starting Codex. The plugin references the variable name and never stores the value, so no token is written to ~/.codex/config.toml:

export CONTEXT7_API_KEY_CODEX="<your-context7-api-key>"

Put that in your shell profile so every Codex session inherits it. Get the key from your own context7 account and keep the value out of the repository. If you store it in a secret manager, substitute your own vault and item names (with the 1Password CLI the reference is op://<vault>/<item>/credential), and cache the resolved value instead of re-reading the vault in every shell: each raw read is a separate unlock prompt.

Two behaviors worth knowing:

A server you already define yourself under [mcp_servers.context7] in ~/.codex/config.toml wins, and the plugin's definition is ignored entirely (including its tool scoping). That is intentional: your own configuration is never overridden. Remove your entry if you want the plugin's.
Without a valid key the server still connects and still lists its tools. Only a real call fails, with Invalid API key. A successful connection is therefore not proof of authentication.

pi

pi (0.85) reads the same SKILL.md format, and the repo now carries a pi manifest, so the package installs directly:

pi install git:github.com/yonatangross/orchestkit

That registers every skill. Add -l to write .pi/settings.json in the project instead of your user settings. Pointing pi at a checkout still works and needs no install (pi --skill ./plugins/ork/skills).

The 29 skills marked disable-model-invocation stay reachable only as /skill:<name>. Two measured caveats: --no-builtin-tools hides every skill (pi lists skills only when a file-reading tool is enabled), and pi -p blocks on an open stdin, so headless runs need </dev/null.

MCP servers for pi come from .pi/mcp.json, then .mcp.json, then ~/.config/mcp/mcp.json. Copy the shipped template to get the recommended servers with a read-only includeTools allowlist per server:

cp .pi/mcp.json.example .pi/mcp.json

Full detail and the tracking epic: OrchestKit on pi, Codex and Cursor.

FAQ

/plugin list
/plugin uninstall ork && /plugin install ork

Run /ork:doctor to diagnose.

Requires ≥2.1.251 (supported floor; Opus 5 as the default Opus, xhigh effort, dynamic workflows, sandbox.network.strictAllowlist, native binary, hardened Bash(rm:*)/Bash(find:*) rules). Check with claude --version.

Raising this floor is a breaking change and ships as a major release. See STABILITY.md for the full contract, and shared/cc-support.json for the authoritative window.

Complementary, not a rival listing. Superpowers (official Anthropic marketplace) is process — how the agent works a task. OrchestKit is production patterns plus lifecycle hooks. Honest split: docs · yonyon.ai.

Development

npm run build      # Build plugins from src/
npm test           # Run all tests

Edit src/ and manifests/, never plugins/ (generated).

See CONTRIBUTING.md for details.

What's New

v10.0.0-beta.11 · 2026-09-08

codex: ship the ork-mech profile and the plugin cache-lag note (#4012)

v10.0.0-beta.10 · 2026-09-08

cursor: export rules to .cursor-plugin and rewrite wrapper paths at generation time (#4011)
pi: ship a pi manifest and a .pi/mcp.json allowlist template (#4009)

v10.0.0-beta.9 · 2026-09-08

engines: pi, Codex and Cursor guide, matrix and audit (#4006)

v10.0.0-beta.8 · 2026-09-08

deps: ignore vitest major under /src/hooks (#3996)

v10.0.0-beta.7 · 2026-09-08

ci: report an unreadable version as SKIP, not DRIFT (#3989)
rules: scope the modules-key ban to shipped hooks.json (#3993)
playground: treat .claude/rules/ as inert (#3994)

v10.0.0-beta.6 · 2026-09-08

docs: drop private-plugin specifics from public source (#3990)

v10.0.0-beta.5 · 2026-09-07

skills: page-serve, hand a human a page at a port-free URL (#3899) (#3987)
hooks: PHONE_RE no longer redacts numeric MCP ids (#3894) (#3984)
tests: Test 4c reads all input, no grep -q SIGPIPE (#3974) (#3982)
glyph: a page an agent can route a human to (#3901) (#3988)

v10.0.0-beta.4 · 2026-09-07

deps-dev: bump the vitest group across 1 directory with 2 updates (#3978)
deps-dev: bump vitest from 4.1.11 to 5.0.0 (#3960)
deps: bump the npm-minor-patch group across 1 directory with 7 updates (#3965)
deps: bump the remotion group across 1 directory with 21 updates (#3964)
bump anthropics/claude-code-action (#3968)
…and 1 more (see CHANGELOG.md)

See CHANGELOG.md for the full release history.

Community

Join the Building with AI community for AI dev tips, OrchestKit support, and connecting with other builders:

Room	Who it's for	Link
Building with AI	The umbrella community. One join, every room below.	Join
Builders	For people already building	Join
OrchestKit	For OrchestKit users	Join
AI for Business	For people leading AI adoption	Join

Names and audiences match what yonyon.ai renders, so the two surfaces cannot drift. Every link resolves through yonyon.ai/go/*, so a rotated invite never needs a README change and no raw invite is published here.

Who builds this

OrchestKit is built and maintained by Yonatan Gross — Yonyon AI, an AI consulting practice. It is the toolkit extracted from real client work, not a side project: the patterns here are the ones that survived shipping.

It stays MIT and free. Nothing is gated, and none of the below changes that.

Working out where AI actually fits in your business? The AI readiness audit is a free assessment that maps your workflows and returns a prioritized report — the same diagnostic that opens a consulting engagement.

Want the toolkit running properly in your team? Setup, configuration, and a working agent loop tailored to your stack is something I do as a fixed-scope engagement. Start a discussion or reach out through the community.

Security policy and reporting: SECURITY.md.

Docs · Issues · Discussions · Community

MIT License · @yonatangross

Orchestkit

At a glance

README

Contents

Quick Start

Host support matrix

Claude Code

Cursor

skills.sh (Cursor, Codex, OpenCode, …)

Why OrchestKit?

What You Get

Key Commands

Configuration

Recommended MCP Servers

Customizing skills

What OrchestKit observes

Install

Cursor

Codex

Unattended runs: the `ork-mech` profile

Keeping the install current

Documentation lookup (context7)

pi

FAQ

Development

What's New

Community

Who builds this

Comments (0)

Orchestkit

At a glance

README

Contents

Quick Start

Host support matrix

Claude Code

Cursor

skills.sh (Cursor, Codex, OpenCode, …)

Why OrchestKit?

What You Get

Key Commands

Configuration

Recommended MCP Servers

Customizing skills

What OrchestKit observes

Install

Cursor

Codex

Unattended runs: the ork-mech profile

Keeping the install current

Documentation lookup (context7)

pi

FAQ

Development

What's New

Community

Who builds this

Comments (0)

Unattended runs: the `ork-mech` profile