Documentation

Every skill in a cloud has a depth between 0 and 1, shown as a score out of 10. The sphere's size follows that depth, so a cloud can be read at a glance: big spheres are what the person is deep in, small ones are working knowledge or interests.

Where depth comes from. When a cloud is built from a résumé, depth reflects evidence in the text, not self-assessment: repeated, senior, long-running work on a topic scores high; a single mention scores low. Roughly: 2/10 is a mentioned interest, 5/10 working knowledge, 8/10 deep sustained experience, 9.5/10 expert-level evidence across many contexts.

The depth budget. The total depth across a cloud is capped by experience: a cloud earns a budget of min(18, 3 + 1.1 × years) total points, where years is the person's estimated professional experience. If a cloud's skills add up to more than the budget, every depth is scaled down proportionally. That is why adding skills dilutes the rest: nobody is 10/10 in a hundred topics, and the budget makes breadth visibly trade off against depth.

Manually added skills. When you add a skill yourself (in your cloud, or claiming one from a project), you state your years of hands-on experience with it and the depth follows 0.15 + 0.09 × years, capped between 1.5/10 and 9.5/10, so about 4 years lands at working knowledge and about 7 years at deep experience. The skill is marked as manually added, and the overall budget still applies afterwards.

Versioning. Clouds carry the version of the scoring method that built them. When the method improves, older clouds show a rebuild notice so their scores stay comparable with everyone else's.

Most people use PairHarbor from the agent they already run. PairHarbor ships an MCP server, so Claude Code, Codex, Claude Desktop or any other MCP client can read and update your cloud and work inside your workspaces as tools: you say what you want, the agent makes the call. It authenticates with a personal API token and talks to the v1 API below, so every safety filter, membership gate and write limit applies unchanged.

1. Create an agent for this machine in Settings (Agents), press New token, and export the token as PAIRHARBOR_TOKEN in your environment. Never commit it.
2. Register the server with your client. The package is pairharbor-mcp on npm and needs Node 20 or newer; npx fetches it on first use. Claude Code reads .mcp.json in the project (or your user settings); Codex reads ~/.codex/config.toml. The server runs on your machine and only calls this API with your token.

{
  "mcpServers": {
    "pairharbor": {
      "command": "npx",
      "args": ["-y", "pairharbor-mcp"],
      "env": { "PAIRHARBOR_TOKEN": "ph_your_token" }
    }
  }
}

Then talk to it. Every request sample in this document has a “Claude Code / Codex” tab with the sentence to type; the agent picks the tool and makes the call as you.

Tools, as in the package README. Your cloud: whoami, get_my_cloud, update_my_cloud, add_skills, remove_skills. Workspaces and projects: list_workspaces, get_workspace_usage, list_workspace_projects, post_workspace_project, post_public_project, update_public_project, delete_workspace_project. Tasks and agents: list_my_tasks, list_workspace_tasks, get_task, create_task, approve_task, claim_task, update_task, complete_task, suggest_assignees, wait_for_tasks. Every tool acts as you, and task history names the agent whose token was used. There is deliberately no extraction tool: mapping a résumé or a project description stays in the signed-in app, and the tools take ready-made skills.

Plan a project from your agent

With the server connected, planning a workspace project is a conversation, covered by the subscription you already pay for. Ask for the plan first, then for the filing:

Plan the project "<title>" in my <workspace> workspace on PairHarbor.
Read its brief, skills and terms, suggest who covers each task, and show me
the plan. When I say "file them", create the tasks.

The agent uses the same tools you would (list the project, suggest assignees, create tasks). Tasks it files are proposals until a member approves them, or go live at once if the workspace runs unattended mode.

Claude Desktop: one-click bundle

Claude Desktop installs local MCP servers from a bundle file, so there is nothing to type. Download pairharbor-mcp.mcpb (version 0.5.6, the same server as the npm package), open it with Claude Desktop, and paste your token into the “PairHarbor API token” field of the install dialog. Claude Desktop stores the token securely and starts the server on your computer whenever a chat needs it; the server only calls this API. Use a token from the agent you created for that computer, so its actions are recorded under that name.

The same calls the MCP server makes, for scripts and other clients. A personal API token reads and writes your own cloud, nothing else. There is no extraction endpoint: building a cloud from a résumé stays in the signed-in app, and the API takes ready-made skills. If you connected an agent above, you already have a token and can skip step 1.

1. Create a token

1. Open Settings and scroll to Agents.
2. Create an agent named after the machine the script will run on (“Work laptop”, “Build box”) and press New token on its row. A token acts as you; what it does is recorded under the agent's name.
3. Copy the ph_... value immediately. It is shown exactly once; we store only a hash. Treat it like a password.
4. Revoke a leaked or retired token in the same list at any time. You can hold up to 5.

Every request authenticates with the token as a bearer header: Authorization: Bearer ph_your_token

2. Read your cloud

GET /api/v1/cloud returns your private cloud: title, skills with depth and category, estimated years, scoring version, and last update time.

Show me my PairHarbor cloud: title, skills with their depth, and years.

Response:

{
  "title": "John D. · AI Engineering Leader",
  "skills": [
    { "name": "Postgres Tuning", "depth": 0.72, "category": "engineering" },
    { "name": "Team Leadership", "depth": 0.55, "category": "trait", "manual": true }
  ],
  "years": 8,
  "version": 2,
  "updatedAt": "2026-07-31T10:00:00.000Z"
}

3. Import or update your cloud

PUT /api/v1/cloud replaces your cloud's skills (and optionally its title) with what you send. Useful for keeping PairHarbor in sync with a skills file you maintain elsewhere.

Replace my PairHarbor cloud with these skills and call it "My imported cloud":
Rust 0.8 engineering, Causal Inference 0.6 domain, Team Leadership 0.5 trait.

Response:

{ "ok": true, "skills": [ ...the normalized result... ] }

Rules applied to every write: categories are engineering, domain, product, craft, and trait; depths are clamped to 0–1; skill names pass the same safety filters as everywhere else (no emails, credentials, or personal data); and the depth budget re-normalizes the result when your cloud's years are known, so totals stay proportional to experience. The response contains the cloud as actually stored; read it back rather than assuming your input survived unchanged.

4. Account and workspaces

The same token also answers who it belongs to and reaches the workspaces the account is a member of. All of these are scoped exactly like the app: you see only your own account and the workspaces you are in.

GET  /api/v1/me                              # owner id, provider, display name, email, cloud title
GET  /api/v1/workspaces                      # Public first (kind "public"), then your company workspaces
                                             # (kind "company"; invite token on admin rows only)
GET  /api/v1/projects                        # your PUBLIC projects: handle, url, listed, skills, brief
POST /api/v1/projects                        # { title, skills, brief?, employment?, workModes?, country?, city?, list?, teamMin?, teamMax?, startsOn?, endsOn? } -> a public project page, unlisted unless list: true; the brief is public on the page
PATCH /api/v1/projects                       # { handle, brief } set or clear ("") your public project's brief
GET  /api/v1/workspaces/<id>/projects        # a company workspace's projects (members only)
POST /api/v1/workspaces/<id>/projects        # { "title", "skills", "brief"?, "teamMin"?, "teamMax"?, "startsOn"?, "endsOn"? }, ready-made skills; the brief is kept with the project
DELETE /api/v1/workspaces/<id>/projects?id=<projectId>   # poster or admin

Public is the first workspace in the list on purpose: it is the open site, so “which workspace am I in” always has an explicit answer. Posting a public project creates a public page, so it stays unlisted unless you pass list: true, and its brief is shown on that page. Deleting one stays in the app.

5. Tasks and agents

Inside a company workspace, projects split into tasks assigned to members. An agent is a machine, VM or container you run, created under Settings; its tokens act as you, so a script or Claude on that machine sees your workspaces, your task inbox and your cloud, and every change it makes is recorded under the agent's name. The workspace routes below accept either your signed-in session or one of your agents' tokens, so people and their machines use one API.

GET  /api/v1/tasks?status=                    # tasks assigned to you, across workspaces (an agent's inbox)
GET  /api/org/<id>/tasks?projectId=&status=   # a workspace's tasks
POST /api/org/<id>/tasks                       # { projectId, title, description?, skills, assignee?, dueOn? } (dueOn defaults to the project's end date)
GET  /api/org/<id>/tasks/<taskId>              # one task with its audit trail
PATCH /api/org/<id>/tasks/<taskId>             # { claim: true } | { status } | { assignee } | { report, artifacts } | { approve: true } | edits
POST /api/org/<id>/tasks/suggest               # { skills } -> members ranked by coverage

Two rules apply to calls made through a token, because nobody is watching the machine. A task created through a token is a proposal: it stays out of every inbox until a member approves it (PATCH { "approve": true }, optionally with a different assignee) or rejects it, which is how a machine can plan work unattended without anyone being surprised by it. And deleting a task needs a signed-in session. Everything else works the same both ways. When a task is completed, its required skills join the assignee's cloud: new ones at a modest depth, existing ones a little deeper, with a history entry saying so.

To have a machine work your tasks unattended, the npm package ships pairharbor-worker: a loop that pulls your assigned tasks, hands each to a handler (a coding handler that runs Claude Code on a repository branch, an Android emulator operator, or your own module), and reports back with a completion report or a blocked reason. Run it with one of your agents' tokens; the Set up panel in Settings and the package README show the commands.

Three workspace-level controls shape unattended work. A workspace admin can turn on unattended mode (Members, Automation) so tasks created through members' agent tokens go live at once instead of waiting as proposals; the history records the auto-approval. Workers get push delivery through GET /api/v1/tasks/wait?since=&timeout=, a long poll that returns as soon as a task assigned to the token owner changes (the MCP tool is wait_for_tasks; the worker uses it between passes). And admins can register webhooks: HTTPS endpoints that receive a JSON POST per task event with an X-PairHarbor-Signature header (HMAC-SHA256 of the body with the endpoint's secret), for server-hosted bots and integrations.

On trust: an agent always belongs to one person and acts within that person's own memberships, so a person in several workspaces serves all of them with one token and nothing crosses a workspace boundary that the person could not cross. Agents offered publicly, to workspaces their owner is not a member of, are deliberately not part of this design.

Plans: a workspace's plan (see pricing) sets how many members it admits, how many webhooks it may register, and how many tasks agents may mark done per calendar month. Tasks people complete are never counted. At the allowance, an agent's completion is refused with 402 and { "code": "quota" } until a person completes it or an admin upgrades; GET /api/org/<id>/billing (MCP: get_workspace_usage) reports the plan and what is left, so a planner can pace itself.

Errors and limits

The same loop twice: post a project, split it into tasks, people take them, reports come back. The first run is a company workspace with a team of twelve and a fictional QA lead. The second is the Public workspace with nobody but you and Claude Desktop, and it is one you can follow along right now.

Post a project in my Trailhead workspace on PairHarbor titled
"Android release 4.2: 14-day device test" with skills: Android 0.8 engineering,
Mobile QA 0.9 craft, Bug Reproduction 0.8 craft, Regression Testing 0.7 craft,
Espresso 0.5 engineering, Google Play 0.5 domain.

Plan the project "Android release 4.2: 14-day device test" in my
Trailhead workspace on PairHarbor. Read its brief, skills and terms,
check who covers what, and show me the plan before filing anything.

1. Pixel 8 (Android 15): install, sign-in, cloud upload, share       -> Priya  92%
2. Galaxy S24 (One UI 7): same flow plus dark mode and rotation      -> Marcus 88%
3. Low-end device (Android 12, 3 GB): cold start under 4 s           -> Wen    81%
4. Tablet layout (Tab S9): Harbor grid and project dialogs             -> Ana    77%
5. Espresso smoke suite: run nightly, file regressions                 -> Diego  85%
6. Offline and flaky-network behaviour on any device                   -> Lena   74%
...
Say "file them" and I will create the twelve tasks as proposals, due Sep 28.

npx -p pairharbor-mcp pairharbor-worker \
  --handler android-emulator --workspace Trailhead

Who am I on PairHarbor, and which workspaces can I act in?

Post a public project on PairHarbor called "PairHarbor Android app: test round".
Brief: we are testing the Android app (package com.pairharbor.app) on real
phones before it goes to Google Play production. Testers install it, sign in,
build or open a skill cloud, and report what broke.
Skills: Android 0.6 engineering, Mobile QA 0.8 craft, Bug Reproduction 0.7 craft,
Attention to Detail 0.6 trait. It is a short remote project ending in 14 days.
Keep it unlisted for now and give me the link.

Create a task under that project in the Public workspace:
"Install the app and run the first-launch checklist".
Description: 1) install the app from the Play testing link, 2) confirm it opens
full screen with no browser address bar, 3) sign in with Google, 4) open My cloud
and rotate the 3D cloud, 5) open a shared link to pairharbor.com and confirm it
opens in the app, 6) press Back from each screen. Report phone model, Android
version, and anything that failed, with screenshots.
Skills: Mobile QA 0.8 craft, Android 0.5 engineering. Leave it unassigned.

Approve that task so it is open.

Claim that task for me and mark it in progress.

Complete the task with this report: Pixel 8, Android 15. Installed from the
testing link, opened full screen, Google sign-in worked, cloud rotated smoothly.
One problem: Back from the Harbor closed the app instead of returning to My cloud.
Attach https://example.com/screenshots as "Screenshots".

Show me that task with its full history.

Every published cloud has an iframe-friendly page at /u/<handle>/embed: the interactive 3D scene alone, no site chrome, with a small PairHarbor mark linking back to the full page.

1. Publish your cloud (the share button on My cloud). You get a link like pairharbor.com/u/ab12cd34.
2. The handle is the part after /u/. Append /embed to get the embeddable page.
3. Paste the iframe below into your site's HTML.

<iframe
  src="https://pairharbor.com/u/YOUR_HANDLE/embed"
  width="100%"
  height="480"
  style="border: 0; border-radius: 12px"
  loading="lazy"
  title="My skill cloud"
></iframe>

For a responsive embed that keeps its shape on phones, wrap it in an aspect-ratio box instead of a fixed height:

<div style="aspect-ratio: 16 / 9; max-width: 900px">
  <iframe
    src="https://pairharbor.com/u/YOUR_HANDLE/embed"
    width="100%"
    height="100%"
    style="border: 0; border-radius: 12px"
    loading="lazy"
    title="My skill cloud"
  ></iframe>
</div>

Append ?mode=genesis to the embed URL to play the cloud as the Genesis animation (the skills accreting into orbit like a forming solar system, looping) instead of the static sphere.

Good to know: the embed shows exactly what the public page shows, nothing more. It does not need the cloud to be listed in the Harbor, only published. The page is live, so skill edits and renames appear in the embed automatically; revoking the link in Settings kills it. Visitors' browsers render the scene locally with WebGL; browsers without it see a plain fallback. Any site that allows iframes works, including Notion, WordPress, and personal sites.

GitHub README and other no-iframe sites

GitHub profile READMEs (and platforms like dev.to) strip iframes, but they render images. Your cloud's preview card is an image, so this Markdown gives you a branded, clickable card that lands on the live 3D cloud:

[![My skill cloud](https://pairharbor.com/u/YOUR_HANDLE/opengraph-image)](https://pairharbor.com/u/YOUR_HANDLE)

The card regenerates from your current cloud; GitHub caches images for a few hours, so edits take a little while to appear there.