opencode-agents 1.0.7

package/dist/templates/default-agent.md

@@ -0,0 +1,35 @@
+---
+description: my-agent - Add your agent description here
+mode: subagent
+model: anthropic/claude-3-5-sonnet-20241022
+temperature: 0.7
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: false
+  glob: true
+  grep: true
+  task: false
+  skill: false
+hidden: false
+---
+
+# my-agent
+
+You are a custom AI agent. Describe your purpose and behavior here.
+
+## When to Use
+
+Describe when this agent should be invoked.
+
+## Workflow
+
+1. First step...
+2. Second step...
+3. Third step...
+
+## Guidelines
+
+- Add your specific guidelines here
+- Be clear and concise

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "opencode-agents",
+  "version": "1.0.7",
+  "description": "CLI for managing AI coding agents",
+  "type": "module",
+  "bin": {
+    "agents": "./bin/agents.js"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "dev": "node --watch src/index.ts",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "claude",
+    "agent",
+    "cli",
+    "skills"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "degit": "^2.8.4",
+    "gray-matter": "^4.0.3",
+    "ora": "^5.4.1",
+    "chalk": "^5.3.0",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0",
+    "esbuild": "^0.24.0",
+    "vitest": "^1.0.0"
+  }
+}

package/src/commands/add.ts

@@ -0,0 +1,44 @@
+import ora from 'ora';
+import { installAgent } from '../core/installer.js';
+import { detectPlatforms } from '../utils/filesystem.js';
+import { logger } from '../utils/logger.js';
+import type { AgentPlatform, InstallOptions } from '../types/index.js';
+
+interface AddCommandOptions {
+  global: boolean;
+  agent: string[] | undefined;
+  agentName: string | undefined;
+  yes: boolean;
+  copy: boolean;
+}
+
+export async function addCommand(source: string, options: AddCommandOptions): Promise<void> {
+  const spinner = ora('Installing agent...').start();
+
+  try {
+    let platforms: AgentPlatform[];
+    
+    if (options.agent && options.agent.length > 0) {
+      platforms = options.agent as AgentPlatform[];
+    } else {
+      platforms = ['opencode'];
+    }
+
+    const installOptions: InstallOptions = {
+      source,
+      global: options.global,
+      platforms,
+      agentName: options.agentName,
+      copy: options.copy,
+      yes: options.yes,
+    };
+
+    await installAgent(installOptions);
+    
+    spinner.succeed(`Successfully installed agent from ${source}`);
+  } catch (err) {
+    spinner.fail(`Failed to install agent: ${err instanceof Error ? err.message : String(err)}`);
+    logger.error(String(err));
+    process.exit(1);
+  }
+}

package/src/commands/check.ts

@@ -0,0 +1,11 @@
+import chalk from 'chalk';
+import { logger } from '../utils/logger.js';
+
+export async function checkCommand(): Promise<void> {
+  logger.info('Checking for agent updates...');
+  
+  console.log(chalk.yellow('\nNote: Update checking requires version tracking.'));
+  console.log('To update agents, use: npx agents add <source> --force\n');
+  
+  console.log(chalk.dim('Add version info to your agents to enable update checking.'));
+}

package/src/commands/find.ts

@@ -0,0 +1,25 @@
+import chalk from 'chalk';
+import { logger } from '../utils/logger.js';
+
+interface FindCommandOptions {
+}
+
+export async function findCommand(query?: string, _options?: FindCommandOptions): Promise<void> {
+  if (!query) {
+    console.log(chalk.bold('\nSearch for agents\n'));
+    console.log('Usage: npx agents find <query>');
+    console.log('\nExample:');
+    console.log('  npx agents find code-review');
+    console.log('  npx agents find testing');
+    return;
+  }
+
+  logger.info(`Searching for agents matching "${query}"...`);
+
+  console.log(chalk.yellow('\nNote: Agent search functionality requires integration with skills.sh API.'));
+  console.log('For now, you can browse agents at: https://skills.sh\n');
+  
+  console.log(chalk.dim('Alternatively, you can:'));
+  console.log(chalk.dim('  1. Check GitHub for agent repositories'));
+  console.log(chalk.dim('  2. Use "npx agents add <owner/repo>" to install directly'));
+}

package/src/commands/init.ts

@@ -0,0 +1,84 @@
+import { join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { ensureDir, detectPlatforms } from '../utils/filesystem.js';
+import { logger } from '../utils/logger.js';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+interface InitCommandOptions {
+  global?: boolean;
+}
+
+export async function initCommand(name?: string, _options?: InitCommandOptions): Promise<void> {
+  try {
+    const targetName = name || 'my-agent';
+    const targetDir = name ? join(process.cwd(), name) : process.cwd();
+    const targetPath = join(targetDir, `${targetName}.md`);
+
+    if (existsSync(targetPath)) {
+      logger.error(`Agent file already exists at ${targetPath}`);
+      process.exit(1);
+    }
+
+    ensureDir(targetDir);
+
+    let template: string;
+    const templatePath = join(__dirname, '..', '..', 'templates', 'default-agent.md');
+    
+    if (existsSync(templatePath)) {
+      template = readFileSync(templatePath, 'utf-8');
+    } else {
+      template = getDefaultTemplate(targetName);
+    }
+
+    const fs = await import('fs');
+    fs.writeFileSync(targetPath, template, 'utf-8');
+
+    logger.success(`Created agent template at ${targetPath}`);
+    console.log(`\nYou can now edit ${targetPath} to customize your agent.`);
+  } catch (err) {
+    logger.error(`Failed to create agent: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+function getDefaultTemplate(name: string): string {
+  return `---
+description: ${name} - Add your agent description here
+mode: subagent
+model: anthropic/claude-3-5-sonnet-20241022
+temperature: 0.7
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: false
+  glob: true
+  grep: true
+  task: false
+  skill: false
+hidden: false
+---
+
+# ${name}
+
+You are a custom AI agent. Describe your purpose and behavior here.
+
+## When to Use
+
+Describe when this agent should be invoked.
+
+## Workflow
+
+1. First step...
+2. Second step...
+3. Third step...
+
+## Guidelines
+
+- Add your specific guidelines here
+- Be clear and concise
+`;
+}

package/src/commands/list.ts

@@ -0,0 +1,42 @@
+import chalk from 'chalk';
+import { listInstalledAgents } from '../core/installer.js';
+import { detectPlatforms } from '../utils/filesystem.js';
+import { logger } from '../utils/logger.js';
+import type { AgentPlatform } from '../types/index.js';
+
+interface ListCommandOptions {
+  global: boolean;
+  agent: string | undefined;
+}
+
+export async function listCommand(options: ListCommandOptions): Promise<void> {
+  let platforms: AgentPlatform[];
+  
+  if (options.agent) {
+    platforms = [options.agent as AgentPlatform];
+  } else {
+    platforms = ['opencode'];
+  }
+
+  const scope = options.global ? 'global' : 'project';
+  
+  for (const platform of platforms) {
+    const agents = listInstalledAgents(platform, options.global);
+    
+    if (agents.length === 0) {
+      logger.info(`No agents found for ${platform} (${scope})`);
+      continue;
+    }
+
+    console.log(chalk.bold(`\n${platform} agents (${scope}):\n`));
+    
+    for (const agent of agents) {
+      const name = agent.agent.name || agent.path.split(/[/\\]/).pop()?.replace('.md', '') || 'unknown';
+      const mode = agent.agent.mode || 'subagent';
+      const description = agent.agent.description || 'No description';
+      
+      console.log(`  ${chalk.cyan(name)} ${chalk.gray(`[${mode}]`)}`);
+      console.log(`    ${chalk.dim(description)}\n`);
+    }
+  }
+}

package/src/commands/remove.ts

@@ -0,0 +1,42 @@
+import ora from 'ora';
+import { removeAgent } from '../core/installer.js';
+import { detectPlatforms } from '../utils/filesystem.js';
+import { logger } from '../utils/logger.js';
+import type { AgentPlatform } from '../types/index.js';
+
+interface RemoveCommandOptions {
+  global: boolean;
+  agent: string | undefined;
+}
+
+export async function removeCommand(name: string, options: RemoveCommandOptions): Promise<void> {
+  const spinner = ora(`Removing agent "${name}"...`).start();
+
+  try {
+    let platforms: AgentPlatform[];
+    
+    if (options.agent) {
+      platforms = [options.agent as AgentPlatform];
+    } else {
+      platforms = detectPlatforms();
+    }
+
+    let removed = false;
+    
+    for (const platform of platforms) {
+      const result = removeAgent(name, platform, options.global);
+      if (result) {
+        removed = true;
+      }
+    }
+
+    if (removed) {
+      spinner.succeed(`Removed agent "${name}"`);
+    } else {
+      spinner.warn(`Agent "${name}" not found`);
+    }
+  } catch (err) {
+    spinner.fail(`Failed to remove agent: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}

package/src/commands/update.ts

@@ -0,0 +1,12 @@
+import chalk from 'chalk';
+import { logger } from '../utils/logger.js';
+
+export async function updateCommand(): Promise<void> {
+  logger.info('Updating agents...');
+  
+  console.log(chalk.yellow('\nNote: Auto-update functionality coming soon.\n'));
+  
+  console.log(chalk.dim('To update an agent, remove it and reinstall:'));
+  console.log(chalk.dim('  npx agents remove <agent-name>'));
+  console.log(chalk.dim('  npx agents add <source>'));
+}

package/src/core/discover.ts

@@ -0,0 +1,129 @@
+import { join, basename } from 'path';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { parseAgentFile } from './parser.js';
+import { findFiles, isDirectory } from '../utils/filesystem.js';
+import type { AgentFile, Agent } from '../types/index.js';
+
+const SEARCH_DIRECTORIES = [
+  '',
+  'agents',
+  '.agents',
+  '.opencode/agents',
+  'src/agents',
+];
+
+const PRIORITY_FILES = [
+  'AGENTS.md',
+  'SKILL.md',
+  'AGENT.md',
+];
+
+export async function discoverFromDirectory(dir: string): Promise<AgentFile[]> {
+  const agents: AgentFile[] = [];
+
+  for (const subDir of SEARCH_DIRECTORIES) {
+    const searchDir = subDir ? join(dir, subDir) : dir;
+    if (!existsSync(searchDir)) continue;
+
+    const mdFiles = findFiles(searchDir, /\.md$/);
+    
+    for (const file of mdFiles) {
+      const fileName = basename(file);
+      if (fileName.startsWith('.')) continue;
+      if (fileName === 'README.md') continue;
+
+      try {
+        const content = readFileSync(file, 'utf-8');
+        const agentFile = parseAgentFile(content, file);
+        agents.push(agentFile);
+      } catch (err) {
+        continue;
+      }
+    }
+  }
+
+  for (const fileName of PRIORITY_FILES) {
+    const priorityFile = join(dir, fileName);
+    if (existsSync(priorityFile)) {
+      try {
+        const content = readFileSync(priorityFile, 'utf-8');
+        const agentFile = parseAgentFile(content, priorityFile);
+        const exists = agents.some(a => a.path === agentFile.path);
+        if (!exists) {
+          agents.unshift(agentFile);
+        }
+      } catch (err) {
+        continue;
+      }
+    }
+  }
+
+  return agents;
+}
+
+export async function discoverFromRepo(owner: string, repo: string, ref?: string): Promise<AgentFile[]> {
+  const degit = await import('degit');
+  const tempDir = await createTempDir();
+  
+  try {
+    const source = ref ? `${owner}/${repo}#${ref}` : `${owner}/${repo}`;
+    await degit.default(source).clone(tempDir);
+    
+    return discoverFromDirectory(tempDir);
+  } finally {
+    // Cleanup temp directory would happen here in production
+  }
+}
+
+async function createTempDir(): Promise<string> {
+  const { mkdtempSync } = await import('fs');
+  const { tmpdir } = await import('os');
+  return mkdtempSync(join(tmpdir(), 'npx-agents-'));
+}
+
+export function discoverLocal(dir: string): AgentFile[] {
+  const agents: AgentFile[] = [];
+  
+  if (!existsSync(dir)) {
+    return agents;
+  }
+
+  const mdFiles = findFiles(dir, /\.md$/);
+  
+  for (const file of mdFiles) {
+    const fileName = basename(file);
+    if (fileName.startsWith('.') || fileName === 'README.md') continue;
+
+    try {
+      const content = readFileSync(file, 'utf-8');
+      const agentFile = parseAgentFile(content, file);
+      agents.push(agentFile);
+    } catch (err) {
+      continue;
+    }
+  }
+
+  return agents;
+}
+
+export function parseSource(source: string): { type: 'github' | 'local'; owner?: string; repo?: string; path: string } {
+  if (source.startsWith('.') || source.startsWith('/') || /^[a-zA-Z]:\\/.test(source)) {
+    return { type: 'local', path: source };
+  }
+
+  if (source.includes('/') && !source.startsWith('http')) {
+    const parts = source.split('/');
+    if (parts.length >= 2) {
+      return { type: 'github', owner: parts[0], repo: parts[1].replace(/#.+$/, '') };
+    }
+  }
+
+  if (source.startsWith('http://') || source.startsWith('https://')) {
+    const urlMatch = source.match(/github\.com[/:]([^/]+)\/([^/]+)/);
+    if (urlMatch) {
+      return { type: 'github', owner: urlMatch[1], repo: urlMatch[2].replace(/#.+$/, '') };
+    }
+  }
+
+  return { type: 'local', path: source };
+}

package/src/core/installer.ts

@@ -0,0 +1,169 @@
+import { join, basename } from 'path';
+import { existsSync, readdirSync, readFileSync, mkdirSync, copyFileSync, symlinkSync, rmSync } from 'fs';
+import { tmpdir, homedir } from 'os';
+import { mkdtempSync, rmSync as rmSyncFs } from 'fs';
+import { parseAgentFile } from './parser.js';
+import { discoverFromDirectory } from './discover.js';
+import { ensureDir, getPlatformPaths, isDirectory, findFiles } from '../utils/filesystem.js';
+import { logger } from '../utils/logger.js';
+import type { AgentPlatform, AgentFile, InstallOptions } from '../types/index.js';
+
+export async function installAgent(options: InstallOptions): Promise<void> {
+  const { source, global, platforms, agentName, copy } = options;
+  
+  logger.info(`Installing agent from: ${source}`);
+
+  const tempDir = await fetchSource(source);
+  
+  try {
+    const agents = await discoverFromDirectory(tempDir);
+    
+    if (agents.length === 0) {
+      throw new Error('No agents found in the source');
+    }
+
+    for (const platform of platforms) {
+      const targetPaths = getPlatformPaths(platform, global);
+      
+      for (const targetPath of targetPaths) {
+        ensureDir(targetPath);
+        
+        for (const agentFile of agents) {
+          const name = agentName || agentFile.agent.name || basename(agentFile.path, '.md');
+          const finalPath = join(targetPath, `${name}.md`);
+          
+          if (existsSync(finalPath) && !options.yes) {
+            logger.warn(`Agent "${name}" already exists at ${finalPath}`);
+            continue;
+          }
+
+          if (copy) {
+            const sourcePath = agentFile.path;
+            if (isDirectory(sourcePath)) {
+              copyDirectory(sourcePath, join(targetPath, name));
+            } else {
+              copyFileSync(sourcePath, finalPath);
+            }
+            logger.success(`Copied agent "${name}" to ${finalPath}`);
+          } else {
+            const sourceDir = tempDir;
+            try {
+              symlinkSync(sourceDir, finalPath, 'dir');
+              logger.success(`Symlinked agent "${name}" to ${finalPath}`);
+            } catch (err) {
+              logger.warn(`Failed to create symlink, copying instead: ${err}`);
+              copyDirectory(sourceDir, join(targetPath, name));
+              logger.success(`Copied agent "${name}" to ${targetPath}`);
+            }
+          }
+        }
+      }
+    }
+  } finally {
+    if (existsSync(tempDir) && tempDir.startsWith(tmpdir())) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+}
+
+async function fetchSource(source: string): Promise<string> {
+  if (source.startsWith('.') || source.startsWith('/') || /^[a-zA-Z]:\\/.test(source)) {
+    return source;
+  }
+
+  const degit = await import('degit');
+  const tempDir = mkdtempSync(join(tmpdir(), 'npx-agents-'));
+  
+  const parts = source.split('/');
+  let owner = parts[0];
+  let repo = parts[1]?.replace(/#.+$/, '') || '';
+  let ref = '';
+  
+  if (source.includes('#')) {
+    const [repoPart, refPart] = source.split('#');
+    repo = repoPart.split('/')[1];
+    ref = refPart;
+  }
+
+  try {
+    const target = ref ? `${owner}/${repo}#${ref}` : `${owner}/${repo}`;
+    await degit.default(target).clone(tempDir);
+    return tempDir;
+  } catch (err) {
+    rmSync(tempDir, { recursive: true, force: true });
+    throw new Error(`Failed to fetch from ${source}: ${err}`);
+  }
+}
+
+function copyDirectory(source: string, target: string): void {
+  ensureDir(target);
+  const files = readdirSync(source);
+  for (const file of files) {
+    const srcPath = join(source, file);
+    const destPath = join(target, file);
+    if (isDirectory(srcPath)) {
+      copyDirectory(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+export function listInstalledAgents(platform: AgentPlatform, global: boolean): AgentFile[] {
+  const agents: AgentFile[] = [];
+  const paths = getPlatformPaths(platform, global);
+  
+  for (const path of paths) {
+    if (!existsSync(path)) continue;
+    
+    const mdFiles = findFiles(path, /\.md$/);
+    for (const file of mdFiles) {
+      try {
+        const content = readFileSync(file, 'utf-8');
+        const agentFile = parseAgentFile(content, file);
+        agents.push(agentFile);
+      } catch (err) {
+        continue;
+      }
+    }
+  }
+  
+  return agents;
+}
+
+export function removeAgent(name: string, platform: AgentPlatform, global: boolean): boolean {
+  const paths = getPlatformPaths(platform, global);
+  
+  for (const path of paths) {
+    const agentPath = join(path, `${name}.md`);
+    if (existsSync(agentPath)) {
+      rmSync(agentPath, { recursive: true, force: true });
+      logger.success(`Removed agent "${name}" from ${path}`);
+      return true;
+    }
+    
+    if (existsSync(path)) {
+      const entries = readdirSync(path);
+      for (const entry of entries) {
+        const entryPath = join(path, entry);
+        const linkTarget = existsSync(entryPath) ? entryPath : null;
+        if (linkTarget && readlinkCheck(entryPath, name)) {
+          rmSync(entryPath, { recursive: true, force: true });
+          logger.success(`Removed agent "${name}" from ${path}`);
+          return true;
+        }
+      }
+    }
+  }
+  
+  return false;
+}
+
+function readlinkCheck(path: string, name: string): boolean {
+  try {
+    const stat = require('fs').lstatSync(path);
+    return stat.isSymbolicLink() && path.includes(name);
+  } catch {
+    return false;
+  }
+}

package/src/core/parser.ts

@@ -0,0 +1,55 @@
+import matter from 'gray-matter';
+import type { Agent, AgentFile } from '../types/index.js';
+
+export function parseAgentFile(content: string, path: string): AgentFile {
+  const { data, content: body } = matter(content);
+  
+  if (!data.description) {
+    throw new Error(`Agent at ${path} is missing required "description" field in frontmatter`);
+  }
+
+  const agent: Agent = {
+    description: data.description,
+    name: data.name,
+    mode: data.mode,
+    model: data.model,
+    temperature: data.temperature,
+    maxSteps: data.maxSteps,
+    color: data.color,
+    trigger: data.trigger,
+    hidden: data.hidden,
+    tools: data.tools,
+    permission: data.permission,
+    mcp: data.mcp,
+    version: data.version,
+  };
+
+  return {
+    path,
+    agent,
+    content: body.trim(),
+  };
+}
+
+export function parseAgentFromString(content: string, filename: string): AgentFile {
+  const baseName = filename.replace(/\.md$/, '');
+  return parseAgentFile(content, baseName);
+}
+
+export function validateAgent(agent: Agent): string[] {
+  const errors: string[] = [];
+  
+  if (!agent.description) {
+    errors.push('Missing required "description" field');
+  }
+  
+  if (agent.temperature !== undefined && (agent.temperature < 0 || agent.temperature > 1)) {
+    errors.push('Temperature must be between 0 and 1');
+  }
+  
+  if (agent.mode && !['primary', 'subagent', 'all'].includes(agent.mode)) {
+    errors.push('Mode must be "primary", "subagent", or "all"');
+  }
+  
+  return errors;
+}