AgentHarbor Documentation

Installation

Download the latest release from GitHub for your platform:

On macOS, open the DMG and drag AgentHarbor.app into Applications. The app is signed with an Apple Developer ID and notarized. If macOS ever flags it as "damaged" (a rare quarantine-attribute issue), run xattr -cr /Applications/AgentHarbor.app.

AgentHarbor keeps itself up to date: the built-in updater checks GitHub Releases every 4 hours and shows an in-app banner with one-click install (snoozable for 24h).

First Steps

After installing, here's how to get started:

1. Open AgentHarbor — The app starts on the Registry page showing all available capabilities, and its icon appears in your menu bar / system tray.
2. Connect providers — Analytics for Claude Code, Cursor, Codex, and Gemini CLI are auto-detected in most cases; the tray popover shows a Connect button for anything that needs auth.
3. Select a project — Use the project selector to choose a project directory. AgentHarbor detects which adapters the project already uses.
4. Browse capabilities — Filter by type (MCP, Rule, Skill, Hook, Plugin) and select what you want to deploy.
5. Deploy — Click Deploy, choose your target adapter(s), preview the diff, and confirm.

Capabilities

A capability is a deployable configuration unit. AgentHarbor supports six types:

Each capability has a composite ID, version, visibility (public/private/discovered), tags, and adapter compatibility metadata.

Agents

Agents are AI subagents deployed as .md files in agents/*.md. Each agent has:

Example agent file format:

---
name: Code Reviewer
description: Reviews code changes for quality, security, and best practices.
model: opus
color: purple
memory: project
tools:
  - read
  - edit
tags:
  - review
  - quality
required_capabilities:
  - community/typescript-strict
---

You are a meticulous code reviewer. When invoked, you should:

1. Read the changed files carefully
2. Check for security vulnerabilities
3. Verify error handling
4. Ensure consistent coding style
5. Provide constructive feedback with specific line references

Presets

Presets are named groups of capabilities for one-click deployment. AgentHarbor includes bundled presets like "Full-Stack Web" and "Data Science" (read-only), and you can create custom presets from any selection of capabilities — use "Save as preset" from the multi-select bar or any capability detail.

Composite IDs

Every capability and agent uses a composite ID in author/name format, e.g., community/github-mcp. Names must be kebab-case.

community/github-mcp       ✓ valid
my-org/custom-linter       ✓ valid
github_mcp                 ✗ missing author
community/GitHub MCP       ✗ not kebab-case

Claude Code

The Claude Code adapter supports all capability types: MCP, rules, skills, hooks, plugins, and agents.

Cursor

Cursor supports MCP servers, rules, and shared agents. Skill and hook capabilities are not deployed to Cursor (Cursor's own hooks are managed from its sidebar section instead).

Windsurf

Windsurf supports MCP servers and rules only. Agents are not supported.

Gemini CLI

The Gemini CLI adapter deploys skills, hooks, and agents, and its sidebar section manages Gemini's global config, memory, skills, agents, extensions, and analytics (per-model quota and tier info).

Codex

The Codex (OpenAI) adapter deploys MCP servers and skills, and its sidebar section manages the global config, skills, and analytics (rate limits, credits, token usage).

More Adapters

MCP Servers

MCP (Model Context Protocol) servers provide tool capabilities to AI agents. They run as background processes and expose tools via a standard protocol.

{
  "id": "community/github-mcp",
  "type": "mcp",
  "name": "GitHub MCP",
  "version": "1.0.0",
  "content": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": {
        "description": "GitHub personal access token",
        "required": true,
        "secret": true
      }
    }
  }
}

Environment variables marked as secret: true are stored in the OS keychain (macOS Keychain / Windows Credential Manager) and injected at deploy time. Manage them from Settings → Secrets.

The registry can also discover an MCP server's tools live — AgentHarbor connects to the server (stdio or HTTP) and lists what it exposes before you deploy.

Rules

Rules are system prompts or context rules that guide AI behavior. They are deployed as text content to adapter-specific files (e.g., CLAUDE.md or .cursorrules).

{
  "id": "community/typescript-strict",
  "type": "rule",
  "name": "TypeScript Strict",
  "content": {
    "body": "## TypeScript Rules\n- No use of 'any' type\n- Explicit return types on functions\n- Use strict null checks\n- Prefer interfaces over type aliases"
  }
}

Skills

Skills are reusable agent instructions built around a SKILL.md file, optionally with helper files and scripts. They can span multiple files, specify model overrides, and control tool access.

Hooks

Hooks are event-triggered automations. They match specific events (e.g., pre-commit, post-save) and execute shell commands.

{
  "id": "community/pre-commit-lint",
  "type": "hook",
  "content": {
    "event": "pre-commit",
    "matcher": "**/*.{ts,tsx,js,jsx}",
    "command": "npx eslint --fix"
  }
}

Plugins

Plugins provide installation scripts and configuration management. They can set up development environments, install dependencies, and configure tools.

Custom

Use + New in the header to author your own MCP, rule, skill, hook, plugin, or agent. Custom items live in your local registry only (never synced to the community) and are editable and deletable from their detail view. Your custom capabilities can be exported and imported as JSON from Settings → Data Management.

Deploy Wizard

The deploy wizard is a 4-step modal that guides you through the deployment process:

1. Project — Pick a folder; AgentHarbor detects which adapters are usable (.claude/, .cursor/, .windsurfrules, .codex/, etc.). Or choose global scope to target ~/ configs.
2. Adapter Selection — Multi-select target tools, with capability compatibility shown per adapter
3. Preview — A live diff per adapter (split, unified, or raw mode) with a per-file strategy dropdown
4. Success — Files written, "Open in Finder / Cursor / VS Code" buttons, and Undo Deploy

Deploy Strategies

Each file can use a different deploy strategy from the preview step:

A default strategy for JSON files (Merge / Overwrite / Skip) can be set in Settings → Deploy, along with whether backups are created before overwriting.

Backup & Restore

Every deploy automatically creates a backup in ~/Library/Application Support/com.agentharbor.app/backups/ (or the equivalent app-data directory on Windows). Each backup includes a manifest with timestamps and file hashes. Use the "Undo Deploy" button on the success screen or list, restore, and delete older backups from the project view. A launch-time cleanup keeps the per-project backup count bounded.

Drift Detection

AgentHarbor tracks file hashes after each deploy — and writes a <!-- AgentHarbor: Deployed Capabilities --> manifest block into CLAUDE.md and AGENTS.md. When it detects that a config file has been modified outside the app (e.g., by the IDE, a teammate, or manually), a drift indicator badge appears. You can:

• Accept — Accept the external changes as the new baseline
• Restore — Revert to the last deployed state
• View diff — Compare the current state with the deployed state

Providers

Most providers auto-detect existing CLI/IDE auth; others connect via API key, token, or OAuth device flow from the provider status grid.

Menu-Bar Tray

The tray icon shows the most relevant live metric for your active provider, refreshing about every 120 seconds — session percentage for Claude Code, total spend for Cursor, quota for Gemini, and so on. The tray popover has per-provider cards with quota bars, reset times, and a reconnect button that opens browser OAuth directly. The icon switches to a red variant whenever the active provider is in any non-healthy state.

Limit States

Every provider is tracked on a limit-state ladder:

Unauthenticated → ApiDisabled → BillablePaused → SubscriptionIssue
→ RateLimited → Reached → Approaching → Healthy

State transitions fire native notifications (configurable in Settings → Analytics), so you know you're approaching a limit before you hit it.

Cost Engine

The cost engine computes per-model API-equivalent costs — Claude (Opus / Sonnet / Haiku) and Codex models — token-deduplicated across session windows, so subscription usage can be compared to what the same tokens would cost via API.

AI Debate

AI Debate runs a multi-turn, multi-model refinement of an implementation plan with your project context. Point it at a plan (it reads ~/.claude/plans/ and ~/.cursor/plans/), pick the models, and watch them critique and improve it round by round. The debate keeps running while you navigate the app, with a live turn indicator in the sidebar.

AI Recommendations

Claude analyzes your installed AI tools, projects, and registry to suggest high-leverage actions — capabilities worth deploying, configs worth cleaning up. Open it from the tray menu ("AI Recommendations"). Results are cached for 30 minutes.

Token Optimizer

Model routing recommendations computed from your local Claude usage logs: which sessions could have run on a cheaper model, and what that would save. Heuristic-only — no API calls are made and nothing is spent on this analysis.

Switch Model

The "Switch Model" entry under Claude Code retargets Claude Code at a local Ollama model and back — useful for offline work or saving quota on routine tasks.

Registry Sources

The registry merges several sources by capability ID:

• Bundled registry — definitions that ship with the app
• Community registry — synced from the community GitHub repo
• Your custom items — local-only capabilities and agents you author
• Official MCP Registry — live search of registry.modelcontextprotocol.io
• Anthropic Skills & OpenClaw — official Anthropic skills and the community OpenClaw skills registry, plus import of any skill by GitHub URL

Community Sync

Settings → Registry Sync controls the community source: repository URL, branch, poll interval, auto-update, an optional GitHub token for rate limits, and a Sync Now button (⌘R). The status line shows how many capabilities and agents came from the community.