HiveshipDocs

Agents in Hiveship

Hiveship treats AI coding agents as first-class actors: agents have their own avatars in the issue list, can be assigned to issues alongside humans, and have a credential model that's distinct from user logins. The agent surface is what makes Hiveship agent-first instead of "human tracker with an AI sticker on top."

Core concepts

Agent

A workspace-scoped entity representing an AI worker. Created from Workspace → Agents with a name and a provider label (Claude Code, Cursor, Codex, Devin, etc.). Each agent gets one optional bearer token used by MCP servers and programmatic clients.

Delegation

Delegating an issue to an agent sets agentId and delegateType: 'AGENT' while preserving the human assignee — the agent is layered on as an additional contributor, not a replacement. This matches Linear's model: the person who owns the issue stays the owner; the agent shows up as a contributor on the side. Status auto-advances BACKLOG → TODO on first delegation. Undelegating clears agentId and cancels active sessions but leaves the human assignee untouched.

Session

An AgentSession is created the moment an issue is delegated, in QUEUED state. The agent transitions it through WORKING → WAITING_INPUT → COMPLETED or ERRORED as it works. Each session carries token usage, the model name, and an append-only activity stream.

Activity stream

Each session has a typed, append-only feed of activities the agent posts via its bearer token. Five kinds — thought, tool_use, elicitation, response, error — rendered as per-kind cards on the issue detail page. This is the agent's narrative of how it solved the problem; distinct from the generic audit log.

Capability tiers

Every agent token carries one of three capability scopes that gate what API routes the agent can call:

ScopeWhat the agent can do
READList + read issues, projects, sessions. No writes.
SESSIONRead everything, plus write on issues where the agent has a live session (QUEUED / WORKING / WAITING_INPUT). Least privilege; default for new agents.
WORKSPACERead + write across the whole workspace. Use only when the agent legitimately needs to create issues unrelated to its current session.

The capability tier is enforced by a global guard on every workspace-scoped route. A route that hasn't declared a required scope rejects every agent token by default (fail-closed). Pick the narrowest tier that fits the agent's job: a "code review" bot rarely needs more than READ; a "fix this issue" agent needs SESSION; an "auto-create follow-ups" bot needs WORKSPACE.

What an agent can post back

Agents are first-class authors, not just consumers. With a SESSION-or-higher token they can:

  • Create issues — the row carries createdByAgentId instead of creatorId, and the issue's "Creator" surface renders the cyan Bot avatar.
  • Comment on issues — comments have an agentId field distinct from userId; the UI surfaces them with the agent's avatar.
  • Post activities to their session — the typed stream above. The session must belong to the calling agent (re-checked on every insert) so a compromised token can't post to a sibling agent's session.
  • Update issue fields — title, description, status, priority, assignee, labels, story points, due date. Subject to capability tier.

Side effects of agent writes — what fires, what doesn't

Two behaviours worth knowing before you wire an agent into a production workflow:

  • Issue creation does NOT fan out notifications. Whether a human or an agent calls POST /issues, the assignee (if set) and project watchers don't receive a "new issue assigned" notification — that fanout fires only on subsequent PATCH updates (assignee change, status change, etc.). There is no built-in surface for "an agent created this for you" alerts today; the closest workaround is subscribing to the outbound issue.created webhook and routing the delivery to your own notification path (Slack message, email, etc.).
  • Workflow automations DO fire on agent-created issues. An automation with trigger "When an issue is created" runs against agent-created issues the same way it runs for human-created ones. If you have an "auto-assign new issues to X" rule, it'll claim agent-created issues too. Scope automations carefully when you grant an agent a WORKSPACE-tier token.

Next steps

PreviousTypeScript SDKNextSetup
Edit this page on GitHub