A desktop coding agent with free access to frontier models.
TypeScript
import {
AGENT_PLUGIN_V1_SUPPORTED_VERSIONS,
isAgentPluginManifestSchema,
validateAgentPluginV1Manifest,
} from "./agent-plugin-v1.js"
import type { AgentPluginV1Version } from "./agent-plugin-v1.js"
type GithubDiscoveryTreeEntryKind = "blob" | "tree"
export type GithubDiscoveryTreeEntry = {
id: string
kind: GithubDiscoveryTreeEntryKind
path: string
sha: string | null
size: number | null
}
export type GithubDiscoveryClassification =
| "agent_plugin_repo"
| "claude_marketplace_repo"
| "claude_multi_plugin_repo"
| "claude_single_plugin_repo"
| "folder_inferred_repo"
| "unsupported"
export type GithubDiscoveredPluginSourceKind =
| "agent_plugin_manifest"
| "marketplace_entry"
| "plugin_manifest"
| "standalone_claude"
| "folder_inference"
export type GithubDiscoveredPluginComponentKind =
| "skill"
| "command"
| "agent"
| "hook"
| "mcp_server"
| "lsp_server"
| "monitor"
| "settings"
export type GithubDiscoveredPlugin = {
componentKinds: GithubDiscoveredPluginComponentKind[]
componentPaths: {
agents: string[]
commands: string[]
hooks: string[]
lspServers: string[]
mcpServers: string[]
monitors: string[]
settings: string[]
skills: string[]
}
description: string | null
displayName: string
key: string
manifestPath: string | null
metadata: Record<string, unknown>
rootPath: string
selectedByDefault: boolean
sourceKind: GithubDiscoveredPluginSourceKind
sourceSchemaVersion: AgentPluginV1Version | null
supported: boolean
warnings: string[]
}
export type GithubMarketplaceInfo = {
description: string | null
name: string | null
owner: string | null
version: string | null
}
export type GithubRepoDiscoveryResult = {
classification: GithubDiscoveryClassification
discoveredPlugins: GithubDiscoveredPlugin[]
marketplace: GithubMarketplaceInfo | null
warnings: string[]
}
type MarketplaceEntry = {
agents?: unknown
commands?: unknown
description?: unknown
hooks?: unknown
mcpServers?: unknown
name?: unknown
settings?: unknown
skills?: unknown
source?: unknown
}
type PluginMetadata = {
description: string | null
metadata: Record<string, unknown>
name: string | null
}
const KNOWN_COMPONENT_SEGMENTS = ["skills", "commands", "agents"] as const
function normalizePath(value: string) {
return value.trim().replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+$/, "")
}
function joinPath(rootPath: string, childPath: string) {
const root = normalizePath(rootPath)
const child = normalizePath(childPath)
if (!root) return child
if (!child) return root
return `${root}/${child}`
}
function basename(path: string) {
const normalized = normalizePath(path)
if (!normalized) return null
const parts = normalized.split("/")
return parts[parts.length - 1] ?? null
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null
}
function asString(value: unknown) {
return typeof value === "string" && value.trim().length > 0 ? value.trim() : null
}
function pathDirectoryPrefixes(path: string) {
const segments = normalizePath(path).split("/").filter(Boolean)
const prefixes: string[] = []
for (let index = 1; index <= segments.length; index += 1) {
prefixes.push(segments.slice(0, index).join("/"))
}
return prefixes
}
function buildPathSet(entries: GithubDiscoveryTreeEntry[]) {
const knownPaths = new Set<string>()
for (const entry of entries) {
const normalizedPath = normalizePath(entry.path)
if (!normalizedPath) continue
knownPaths.add(normalizedPath)
for (const prefix of pathDirectoryPrefixes(normalizedPath)) {
knownPaths.add(prefix)
}
}
return knownPaths
}
function hasPath(knownPaths: Set<string>, path: string) {
const normalized = normalizePath(path)
return normalized.length > 0 && knownPaths.has(normalized)
}
function hasDescendant(knownPaths: Set<string>, path: string) {
const normalized = normalizePath(path)
if (!normalized) return false
for (const candidate of knownPaths) {
if (candidate === normalized || candidate.startsWith(`${normalized}/`)) {
return true
}
}
return false
}
function readJsonMap(fileTextByPath: Record<string, string | null | undefined>, path: string) {
const text = fileTextByPath[normalizePath(path)]
if (!text) return null
try {
return JSON.parse(text) as unknown
} catch {
return null
}
}
function readPluginMetadata(fileTextByPath: Record<string, string | null | undefined>, rootPath: string, manifestPath?: string | null): PluginMetadata {
const manifestCandidate = manifestPath ? normalizePath(manifestPath) : normalizePath(joinPath(rootPath, ".claude-plugin/plugin.json"))
const explicitManifest = manifestCandidate ? readJsonMap(fileTextByPath, manifestCandidate) : null
if (isRecord(explicitManifest)) {
return {
description: asString(explicitManifest.description),
metadata: explicitManifest,
name: asString(explicitManifest.name),
}
}
const fallbackPluginJson = readJsonMap(fileTextByPath, joinPath(rootPath, "plugin.json"))
if (isRecord(fallbackPluginJson)) {
return {
description: asString(fallbackPluginJson.description),
metadata: fallbackPluginJson,
name: asString(fallbackPluginJson.name),
}
}
return {
description: null,
metadata: {},
name: null,
}
}
function collectComponentPaths(knownPaths: Set<string>, rootPath: string) {
const componentPaths = {
agents: [] as string[],
commands: [] as string[],
hooks: [] as string[],
lspServers: [] as string[],
mcpServers: [] as string[],
monitors: [] as string[],
settings: [] as string[],
skills: [] as string[],
}
const candidates: Array<[keyof typeof componentPaths, string]> = [
["skills", joinPath(rootPath, "skills")],
["skills", joinPath(rootPath, ".claude/skills")],
["commands", joinPath(rootPath, "commands")],
["commands", joinPath(rootPath, ".claude/commands")],
["agents", joinPath(rootPath, "agents")],
["agents", joinPath(rootPath, ".claude/agents")],
["hooks", joinPath(rootPath, "hooks/hooks.json")],
["mcpServers", joinPath(rootPath, ".mcp.json")],
["lspServers", joinPath(rootPath, ".lsp.json")],
["monitors", joinPath(rootPath, "monitors/monitors.json")],
["settings", joinPath(rootPath, "settings.json")],
]
for (const [bucket, candidate] of candidates) {
if (!candidate) continue
if (bucket === "hooks" || bucket === "mcpServers" || bucket === "lspServers" || bucket === "monitors" || bucket === "settings") {
if (hasPath(knownPaths, candidate)) {
componentPaths[bucket].push(candidate)
}
continue
}
if (hasDescendant(knownPaths, candidate)) {
componentPaths[bucket].push(candidate)
}
}
return componentPaths
}
function readStringArray(value: unknown) {
return Array.isArray(value)
? value.flatMap((entry) => {
const normalized = asString(entry)
return normalized ? [normalized] : []
})
: []
}
function declaredComponentPaths(input: {
declared: Partial<Record<keyof GithubDiscoveredPlugin["componentPaths"], unknown>>
knownPaths: Set<string>
rootPath: string
}) {
const collect = (values: unknown, { file, directory }: { file?: boolean; directory?: boolean }) => {
const paths: string[] = []
for (const value of readStringArray(values)) {
const candidate = joinPath(input.rootPath, value)
if (!candidate && !input.rootPath) {
continue
}
if ((directory && hasDescendant(input.knownPaths, candidate)) || (file && hasPath(input.knownPaths, candidate))) {
paths.push(candidate)
}
}
return paths
}
return {
agents: collect(input.declared.agents, { directory: true }),
commands: collect(input.declared.commands, { directory: true }),
hooks: collect(input.declared.hooks, { file: true, directory: true }),
lspServers: [],
mcpServers: collect(input.declared.mcpServers, { file: true }),
monitors: [],
settings: collect(input.declared.settings, { file: true }),
skills: collect(input.declared.skills, { directory: true }),
} satisfies GithubDiscoveredPlugin["componentPaths"]
}
function marketplaceComponentPaths(entry: MarketplaceEntry, knownPaths: Set<string>, rootPath: string) {
return declaredComponentPaths({
declared: {
agents: entry.agents,
commands: entry.commands,
hooks: entry.hooks,
mcpServers: entry.mcpServers,
settings: entry.settings,
skills: entry.skills,
},
knownPaths,
rootPath,
})
}
function hasAnyComponentPaths(componentPaths: GithubDiscoveredPlugin["componentPaths"]) {
return Object.values(componentPaths).some((paths) => paths.length > 0)
}
function componentKindsFromPaths(componentPaths: GithubDiscoveredPlugin["componentPaths"]): GithubDiscoveredPluginComponentKind[] {
const kinds: GithubDiscoveredPluginComponentKind[] = []
if (componentPaths.skills.length > 0) kinds.push("skill")
if (componentPaths.commands.length > 0) kinds.push("command")
if (componentPaths.agents.length > 0) kinds.push("agent")
if (componentPaths.hooks.length > 0) kinds.push("hook")
if (componentPaths.mcpServers.length > 0) kinds.push("mcp_server")
if (componentPaths.lspServers.length > 0) kinds.push("lsp_server")
if (componentPaths.monitors.length > 0) kinds.push("monitor")
if (componentPaths.settings.length > 0) kinds.push("settings")
return kinds
}
function buildDiscoveredPlugin(input: {
componentPathsOverride?: GithubDiscoveredPlugin["componentPaths"] | null
description?: string | null
displayName?: string | null
fileTextByPath: Record<string, string | null | undefined>
key: string
knownPaths: Set<string>
manifestPath?: string | null
rootPath: string
sourceKind: GithubDiscoveredPluginSourceKind
supported?: boolean
warnings?: string[]
}) {
const metadata = readPluginMetadata(input.fileTextByPath, input.rootPath, input.manifestPath)
const manifestDeclaredPaths = declaredComponentPaths({
declared: metadata.metadata,
knownPaths: input.knownPaths,
rootPath: input.rootPath,
})
const componentPaths = input.componentPathsOverride
?? (hasAnyComponentPaths(manifestDeclaredPaths) ? manifestDeclaredPaths : collectComponentPaths(input.knownPaths, input.rootPath))
const displayName = input.displayName?.trim()
|| metadata.name
|| basename(input.rootPath)
|| "Repository plugin"
return {
componentKinds: componentKindsFromPaths(componentPaths),
componentPaths,
description: input.description ?? metadata.description,
displayName,
key: input.key,
manifestPath: input.manifestPath ? normalizePath(input.manifestPath) : (hasPath(input.knownPaths, joinPath(input.rootPath, ".claude-plugin/plugin.json")) ? joinPath(input.rootPath, ".claude-plugin/plugin.json") : null),
metadata: metadata.metadata,
rootPath: normalizePath(input.rootPath),
selectedByDefault: input.supported !== false,
sourceKind: input.sourceKind,
sourceSchemaVersion: null,
supported: input.supported !== false,
warnings: input.warnings ?? [],
} satisfies GithubDiscoveredPlugin
}
function localMarketplaceRoot(entry: MarketplaceEntry) {
if (typeof entry.source === "string") {
return normalizePath(entry.source)
}
if (!isRecord(entry.source)) {
return null
}
if (typeof entry.source.url === "string") {
return null
}
const localPath = asString(entry.source.path)
return localPath ? normalizePath(localPath) : null
}
function pluginRootsFromManifests(entries: GithubDiscoveryTreeEntry[]) {
return entries
.map((entry) => normalizePath(entry.path))
.filter((path) => path.endsWith(".claude-plugin/plugin.json"))
.map((path) => path.slice(0, -"/.claude-plugin/plugin.json".length))
}
function agentPluginManifestCandidates(input: {
entries: GithubDiscoveryTreeEntry[]
fileTextByPath: Record<string, string | null | undefined>
}) {
return input.entries.flatMap((entry) => {
const path = normalizePath(entry.path)
if (entry.kind !== "blob" || (path !== "plugin.json" && !path.endsWith("/plugin.json"))) return []
const value = readJsonMap(input.fileTextByPath, path)
if (!isRecord(value) || !isAgentPluginManifestSchema(value.$schema)) return []
return [{
path,
rootPath: path === "plugin.json" ? "" : path.slice(0, -"/plugin.json".length),
value,
}]
})
}
function agentPluginComponentPaths(input: {
entries: GithubDiscoveryTreeEntry[]
rootPath: string
}) {
const skillsPrefix = joinPath(input.rootPath, "skills")
const skillEntrypoints = input.entries
.filter((entry) => entry.kind === "blob")
.map((entry) => normalizePath(entry.path))
.filter((path) => {
if (!path.startsWith(`${skillsPrefix}/`) || !path.endsWith("/SKILL.md")) return false
return path.slice(skillsPrefix.length + 1).split("/").length === 2
})
.sort()
const mcpPath = joinPath(input.rootPath, "mcp.json")
const hasMcp = input.entries.some((entry) => entry.kind === "blob" && normalizePath(entry.path) === mcpPath)
return {
agents: [],
commands: [],
hooks: [],
lspServers: [],
mcpServers: hasMcp ? [mcpPath] : [],
monitors: [],
settings: [],
skills: skillEntrypoints,
} satisfies GithubDiscoveredPlugin["componentPaths"]
}
function agentPluginAssetWarnings(input: {
componentPaths: GithubDiscoveredPlugin["componentPaths"]
entries: GithubDiscoveryTreeEntry[]
}) {
const extraAssetCount = input.componentPaths.skills.reduce((count, skillPath) => {
const skillDirectory = skillPath.slice(0, -"/SKILL.md".length)
return count + input.entries.filter((entry) => (
entry.kind === "blob"
&& normalizePath(entry.path).startsWith(`${skillDirectory}/`)
&& normalizePath(entry.path) !== skillPath
)).length
}, 0)
return extraAssetCount > 0
? [`${extraAssetCount} additional skill asset${extraAssetCount === 1 ? " was" : "s were"} found. OmniRush.ai imports the SKILL.md entrypoint; referenced skill assets are not installed yet.`]
: []
}
function inferredRootsFromKnownFolders(entries: GithubDiscoveryTreeEntry[]) {
const inferred = new Set<string>()
for (const entry of entries) {
const normalized = normalizePath(entry.path)
if (!normalized) continue
const segments = normalized.split("/")
for (let index = 0; index < segments.length; index += 1) {
const segment = segments[index]
if (!KNOWN_COMPONENT_SEGMENTS.includes(segment as (typeof KNOWN_COMPONENT_SEGMENTS)[number])) {
continue
}
const rootSegments = segments.slice(0, index)
if (rootSegments.length === 1 && rootSegments[0] === ".claude") {
inferred.add("")
continue
}
inferred.add(rootSegments.join("/"))
break
}
}
return [...inferred]
}
export function buildGithubRepoDiscovery(input: {
entries: GithubDiscoveryTreeEntry[]
fileTextByPath: Record<string, string | null | undefined>
}) {
const knownPaths = buildPathSet(input.entries)
const warnings: string[] = []
if (hasPath(knownPaths, ".claude-plugin/marketplace.json")) {
const marketplaceJson = readJsonMap(input.fileTextByPath, ".claude-plugin/marketplace.json")
const marketplaceEntries = isRecord(marketplaceJson) && Array.isArray(marketplaceJson.plugins)
? marketplaceJson.plugins.filter(isRecord) as MarketplaceEntry[]
: []
const marketplaceInfo: GithubMarketplaceInfo = isRecord(marketplaceJson)
? {
description: asString(marketplaceJson.description),
name: asString(marketplaceJson.name),
owner: isRecord(marketplaceJson.owner)
? asString(marketplaceJson.owner.name) ?? asString(marketplaceJson.owner.login) ?? asString(marketplaceJson.owner)
: asString(marketplaceJson.owner),
version: asString(marketplaceJson.version),
}
: { description: null, name: null, owner: null, version: null }
const discoveredPlugins = marketplaceEntries.map((entry, index) => {
const rootPath = localMarketplaceRoot(entry)
if (rootPath === null) {
const warning = "Marketplace entry points at an external source and cannot be auto-mapped from this connected repo yet."
warnings.push(warning)
return buildDiscoveredPlugin({
description: asString(entry.description),
displayName: asString(entry.name) ?? `Marketplace plugin ${index + 1}`,
fileTextByPath: input.fileTextByPath,
key: `marketplace:${asString(entry.name) ?? index}`,
knownPaths,
manifestPath: null,
rootPath: "",
sourceKind: "marketplace_entry",
supported: false,
warnings: [warning],
})
}
return buildDiscoveredPlugin({
componentPathsOverride: (() => {
const override = marketplaceComponentPaths(entry, knownPaths, rootPath)
return hasAnyComponentPaths(override) ? override : null
})(),
description: asString(entry.description),
displayName: asString(entry.name),
fileTextByPath: input.fileTextByPath,
key: `marketplace:${rootPath}`,
knownPaths,
manifestPath: joinPath(rootPath, ".claude-plugin/plugin.json"),
rootPath,
sourceKind: "marketplace_entry",
})
})
return {
classification: "claude_marketplace_repo",
discoveredPlugins,
marketplace: marketplaceInfo,
warnings,
} satisfies GithubRepoDiscoveryResult
}
// Preserve the existing Claude-compatible interpretation when a repository
// deliberately carries both formats. Agent Plugins become the repo format
// only when no explicit Claude plugin manifest is present.
const manifestRoots = [...new Set(pluginRootsFromManifests(input.entries))]
const agentPluginCandidates = manifestRoots.length === 0 ? agentPluginManifestCandidates(input) : []
if (agentPluginCandidates.length > 0) {
const discoveredPlugins = agentPluginCandidates.map((candidate) => {
const validation = validateAgentPluginV1Manifest(candidate.value)
const componentPaths = validation.ok
? agentPluginComponentPaths({ entries: input.entries, rootPath: candidate.rootPath })
: {
agents: [],
commands: [],
hooks: [],
lspServers: [],
mcpServers: [],
monitors: [],
settings: [],
skills: [],
}
const componentKinds = componentKindsFromPaths(componentPaths)
const componentWarnings = validation.ok
? agentPluginAssetWarnings({ componentPaths, entries: input.entries })
: []
const hasSupportedComponents = componentPaths.skills.length > 0 || componentPaths.mcpServers.length > 0
const validationWarnings = validation.ok ? validation.warnings : [...validation.warnings, ...validation.errors]
const noComponentsWarning = !validation.ok || hasSupportedComponents
? []
: ["This Agent Plugin has no skills or MCP configuration that OmniRush.ai can import."]
const manifestName = typeof candidate.value.name === "string" ? candidate.value.name : null
const manifestDescription = typeof candidate.value.description === "string" ? candidate.value.description : null
return {
componentKinds,
componentPaths,
description: manifestDescription,
displayName: manifestName || basename(candidate.rootPath) || "Agent Plugin",
key: `agent-plugin:${candidate.rootPath || "root"}`,
manifestPath: candidate.path,
metadata: validation.ok ? validation.manifest : {},
rootPath: candidate.rootPath,
selectedByDefault: validation.ok && hasSupportedComponents,
sourceKind: "agent_plugin_manifest",
sourceSchemaVersion: validation.ok ? validation.schemaVersion : null,
supported: validation.ok && hasSupportedComponents,
warnings: [...validationWarnings, ...componentWarnings, ...noComponentsWarning],
} satisfies GithubDiscoveredPlugin
})
return {
classification: "agent_plugin_repo",
discoveredPlugins,
marketplace: null,
warnings: discoveredPlugins.flatMap((plugin) => plugin.warnings.map((warning) => `${plugin.displayName}: ${warning}`)),
} satisfies GithubRepoDiscoveryResult
}
if (manifestRoots.length > 0) {
const discoveredPlugins = manifestRoots.map((rootPath) => buildDiscoveredPlugin({
fileTextByPath: input.fileTextByPath,
key: `manifest:${rootPath || "root"}`,
knownPaths,
manifestPath: joinPath(rootPath, ".claude-plugin/plugin.json"),
rootPath,
sourceKind: "plugin_manifest",
}))
return {
classification: manifestRoots.length === 1 && manifestRoots[0] === "" ? "claude_single_plugin_repo" : "claude_multi_plugin_repo",
discoveredPlugins,
marketplace: null,
warnings,
} satisfies GithubRepoDiscoveryResult
}
// Intentionally disabled for now: directory-based inference can over-classify
// arbitrary repos as plugins. Until we support a broader compatibility model,
// discovery should only accept explicit Claude plugin markers.
// const inferredRoots = inferredRootsFromKnownFolders(input.entries)
// const standaloneRoot = inferredRoots.includes("") && (
// hasDescendant(knownPaths, ".claude/skills")
// || hasDescendant(knownPaths, ".claude/commands")
// || hasDescendant(knownPaths, ".claude/agents")
// )
// const folderRoots = standaloneRoot ? inferredRoots : inferredRoots.filter((root) => root !== "")
//
// if (folderRoots.length > 0) {
// const discoveredPlugins = folderRoots.map((rootPath) => buildDiscoveredPlugin({
// fileTextByPath: input.fileTextByPath,
// key: `${standaloneRoot && rootPath === "" ? "standalone" : "folder"}:${rootPath || "root"}`,
// knownPaths,
// rootPath,
// sourceKind: standaloneRoot && rootPath === "" ? "standalone_claude" : "folder_inference",
// }))
//
// return {
// classification: "folder_inferred_repo",
// discoveredPlugins,
// warnings,
// } satisfies GithubRepoDiscoveryResult
// }
warnings.push(`OmniRush.ai supports Agent Plugins ${AGENT_PLUGIN_V1_SUPPORTED_VERSIONS.join(" and ")} and Claude-compatible plugins. Add a standards-compliant plugin.json, .claude-plugin/marketplace.json, or .claude-plugin/plugin.json to this repository.`)
return {
classification: "unsupported",
discoveredPlugins: [],
marketplace: null,
warnings,
} satisfies GithubRepoDiscoveryResult
}