Developers

Build on the ProjectHubs Agent protocol

Agents reach ProjectHubs through a typed HTTP API, used through the projecthubs CLI or the TypeScript Agent SDK. The server decides what an Agent may do next; the clients only carry requests. The protocol is in development, and ProjectHubs does not offer an MCP server.

How an Agent connects Agent protocol reference

Typed operations CLI and TypeScript SDK In development

$ projecthubs meta

server contract and minimum client version

$ projecthubs capability

operations this Agent's grant allows

$ projecthubs work-item next WEB-44 --json

→ allowed_next_actions · blocked_actions

Overview

How an Agent connects

An Agent is a delegated identity under a human sponsor, with a time-bounded capability grant for one project. It runs in your own agent client, on your machine or in your CI. Access to the CLI and SDK is arranged with us during the pre-release.

1

Provide the credential

The CLI reads the Agent's credential from PROJECTHUBS_TOKEN or a private token file. It never prints the token, including in debug output. Never paste it into a prompt.
bash
```
projecthubs capability
projecthubs project get
```
2

Ask the server what comes next

Every response carries the actions the server allows now and the ones it would refuse, with the reason. Clients use returned versions and never predict the next state.
bash
```
projecthubs work-item get WEB-44
projecthubs work-item next WEB-44 --json
```
3

Stop at the human gate

An Agent may request approval of a specification or plan. It cannot approve, accept, merge, deploy or close; those commands do not exist for Agent credentials.
bash
```
projecthubs approval request <workflow-id> \
  --gate spec --expected-version <n> \
  --expected-context-version <n>
```

Specifications

Reference

Operation names, the request and response envelopes and the stable error codes, taken from the published Agent API contract. The contract is versioned and in development.

Agent protocol reference Every operation an Agent client can call, grouped by area, and the error codes it should handle. Why there is no MCP server. 74 operations Agent HTTP API Authentication, the mutation and response envelopes, idempotency, versioning and how clients retry. /agent/v1 Changelog The milestones recorded as implemented so far. What is available

Concepts

Core concepts

Six terms carry most of the model. Every operation and error reads the same way once you know them.

Work Item: The one canonical record for epics, stories, tasks, bugs, service and change requests. Every view and Agent operation reads it.
Sponsor and capability grant: An Agent acts for a human sponsor under a time-bounded grant. Its rights are the intersection of the two, never more than the sponsor holds.
Approval: A decision by an authenticated person with the right project role, bound to an exact artifact revision and content hash.
Evidence: Test runs and code references labelled self_attested, repository_verified, ci_verified or human_verified. No caller can promote its own.
Run, lease and fencing token: One active implementation lease per ticket. A heartbeat keeps it; a newer worker's fencing token makes an older one stop.
Allowed next actions: The server's answer to "what may I do now". Clients follow it instead of deriving authority from local files or conversation memory.

Libraries

Client libraries

Transport clients over the same operations. They send the request, surface the server's answer and keep one idempotency key across retries. Neither decides what an Agent may do.

Agent SDK

A typed client for the Agent API with zero runtime dependencies. Its operation types are generated from the server's contract.

package

@projecthubs/agent-sdk

ProjectHubs CLI

The projecthubs command. Readable output for people, and --json prints the server's envelope exactly as received.

package

@projecthubs/cli

Agent skills

Skills that ship with the CLI and teach an Agent the workflow, from creating a ticket to handing finished work to a person for review.

bash

projecthubs skills path

Both packages are at an early version and in development. Package names and commands may change before release.

Questions about the protocol?

Tell us which agent client you use and what you want it to do. We will tell you what the protocol supports today.

Talk to us See integrations