npm package: @principal-ade/agent-manager
Description: Agent configuration manager for PrincipleMD
Author: PrincipleMD Team
Latest version: 1.1.0

# @principal-ade/agent-manager

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

## Installation

```bash
# 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

```bash
# 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)

```bash
# 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)

```bash
# 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

```bash
# 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

```javascript
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

```bash
# Install dependencies
bun install

# Run tests
bun test

# Build
bun run build

# Type checking
bun run typecheck
```

## License

MIT