@principal-ade/agent-manager

Agent configuration manager for AI assistants (Claude, Cline, OpenCode).

Installation

# Install globally for CLI usage
npm install -g @principal-ade/agent-manager

# Or use with npx (no installation needed)
npx @principal-ade/agent-manager claude status

# Or install as a library
npm install @principal-ade/agent-manager

CLI Usage

Claude Commands

# Enable hooks with configuration
agent-manager claude enable-hooks --port 3043 --dir ~/.principle/hooks

# Disable all hooks
agent-manager claude disable-hooks

# Check hooks status
agent-manager claude status

Register the Principal MCP server (defaults to npx @principal-ai/principal-mcp)

agent-manager claude enable-principal-mcp

Register using a local bundle

agent-manager claude enable-mcp --server-path ~/.local/bin/principal-ai-mcp-server.js

Remove the MCP server

agent-manager claude disable-principal-mcp

Check MCP registration

agent-manager claude principal-mcp-status

Cline Commands (100% Claude-compatible)

# Enable hooks (uses same format as Claude)
agent-manager cline enable-hooks --port 3043 --dir ~/.principle/hooks
# Disable all hooks
agent-manager cline disable-hooks
# Check hooks status
agent-manager cline status
# MCP helpers
agent-manager cline enable-principal-mcp
agent-manager cline disable-principal-mcp
agent-manager cline principal-mcp-status
agent-manager cline enable-mcp
agent-manager cline disable-mcp
agent-manager cline mcp-status

OpenCode Commands (Plugin System)

# Enable the monitoring plugin
agent-manager opencode enable-plugin --port 3043

# Enable locally (project-specific)
agent-manager opencode enable-plugin --local --port 3043

# Disable the plugin
agent-manager opencode disable-plugin

# Check plugin status
agent-manager opencode status

# MCP helpers
agent-manager opencode enable-principal-mcp
agent-manager opencode disable-principal-mcp
agent-manager opencode principal-mcp-status

Droid Commands

# Enable hooks with configuration
agent-manager droid enable-hooks --port 3043 --dir ~/.principle/hooks

# Disable all hooks
agent-manager droid disable-hooks

# Check hooks status
agent-manager droid status

# Register the Principal MCP server (defaults to npx @principal-ai/principal-mcp)
agent-manager droid enable-principal-mcp

# Register using a local bundle
agent-manager droid enable-mcp --server-path ~/.local/bin/principal-ai-mcp-server.js

# Remove the MCP server
agent-manager droid disable-principal-mcp

# Check MCP registration
agent-manager droid principal-mcp-status

Options

• --port <port> - HTTP port(s) to send events to (can be specified multiple times)
• --dir <directory> - Directory for file storage (fallback or primary)
• --server-path <path> - When enabling MCP, use a local bundle via node <path> instead of npx
• --command <command> / --args <args...> - Override the MCP launch command and arguments
• --env <key=value> - Provide environment variables for the MCP command

Library Usage

import { ClaudeConfigManager } from '@principal-ade/agent-manager';

const manager = new ClaudeConfigManager();

// Enable hooks programmatically
await manager.enableHooks({
  port: [3043, 3044],
  dir: '~/.principle/hooks'
});

// Check status
const status = await manager.getHookStatus();

// Disable hooks
await manager.disableHooks();

Features

• ✅ Support for Claude, Cline, OpenCode, and Droid agents
• ✅ Support for all 9 Claude/Cline/Droid hook events
• ✅ OpenCode plugin management system
• ✅ MCP registration commands for all agents (defaults to npx @principal-ai/principal-mcp)
• ✅ Multiple port configuration for failover
• ✅ File storage fallback
• ✅ Dual usage: CLI tool and Node.js library
• ✅ Full TypeScript support
• ✅ 100% test coverage

Hook Events Supported

1. PreToolUse - Before processing a tool call
2. PostToolUse - After a tool successfully completes
3. Notification - When Claude needs permission or prompt is idle 60+ seconds
4. UserPromptSubmit - When user submits a prompt
5. Stop - When main agent finishes responding
6. SubagentStop - When a subagent (Task tool) finishes
7. PreCompact - Before compact operations
8. SessionStart - When starting/resuming a session
9. SessionEnd - When a session ends

Development

# Install dependencies
bun install

# Run tests
bun test

# Build
bun run build

# Type checking
bun run typecheck

License

MIT