Open source · MIT · v0.6

Work across trackers.
Keep one safe API.

One typed TypeScript SDK for GitHub, GitLab, Linear, Jira, and Azure DevOps. Preview the exact change, coordinate retries, then commit with an explicit receipt.

Start building Browse source
5
adapters
211
tests
0
runtime deps
A prepared change clears the fingerprint, claim and revision gates, then commits through one adapter.A duplicate retry with the same key stops at the claim with WorkInFlightError.

One normalized model for

GitHub Issues GitLab Linear Jira Azure DevOps

Compare providers

One safe-write protocol

Write one change.
Commit through any adapter.

The provider can change. Your prepare → inspect → commit boundary stays the same.

agent-safe-update.ts
import { createWorkClient } from "work-sdk";
import { github } from "work-sdk/github";

const work = createWorkClient({
  adapter: github({
    owner: "acme",
    repo: "api",
    token: process.env.GITHUB_TOKEN!
  }),
});

const change = await work.prepareUpdate(
  "481",
  { state: "done" },
);

await work.commit(change, {
  idempotencyKey: "merge:api#481",
});

Proposed change

acme/api#481

stateopen→closed
!

Mapped ‘done’ to GitHub’s closed state

Inspect exact changes and provider warnings before anything is written.

A safer primitive

Prepare. Inspect. Commit.

Turn an irreversible API call into a change you can reason about, approve, log, and replay.

  1. 01 / Prepare

    Build a change plan

    Fetch current state, normalize provider semantics, and calculate the exact diff.

    work.prepareUpdate(…)
  2. 02 / Inspect

    See what will happen

    Review field changes, lossy mappings, unsupported capabilities, and expected revision.

    change.warnings
  3. 03 / Commit

    Commit with a receipt

    Verify the plan, atomically claim the business key, check the revision, then record or reconcile the outcome.

    work.commit(change)

Small API, serious guarantees

Infrastructure for trustworthy agent actions.

Integrity-checked changes

A prepared change carries a fingerprint. Mutate it after inspection and the SDK rejects the commit.

PreparedWorkChangeacme/api#481

−stateopen

+stateclosed

fingerprint9c2e41d0…7af3

WorkValidationErrorPrepared change was modified after preparation

Atomic retry coordination

Only one worker claims an intent. Uncertain provider outcomes become explicit errors instead of blind retries.

CommitResultreplay
action
"update"
replayed
true
key
merge:api#481

Capability discovery

Check support instead of asking an agent to guess.

azureDevOps.capabilities
customStates
true
concurrency.update
"atomic"
multipleAssignees
false

Normalized errors

Handle auth, rate limits, conflicts, and unsupported fields consistently.

  • WorkConflictErrorconflict
  • WorkRateLimitErrorrate_limit
  • WorkAmbiguousCommitErrorambiguous

Strictly typed

ESM and CommonJS builds, zero runtime dependencies, Node.js 20+.

0
runtime deps
211
tests
20+
Node.js

Incidents prevented

Agents can write code.
Trackers still make them guess.

Provider APIs disagree on states, identities, revisions, rich text, and error shapes. Work SDK puts those differences behind a typed, inspectable boundary.

INC-01Prevented

Wrong transition

“Done” can mean a state, transition ID, or a closed flag. Resolve intent against the provider before writing.

state: "done"Jira transition 31
INC-02Prevented

Duplicate comment

A timeout does not say whether a write succeeded. Atomic claims block concurrent duplicates; ambiguous outcomes stop retries for reconciliation.

retry · same keyWorkInFlightError
INC-03Prevented

Stale overwrite

An item can change between read and write. Revision checks stop agents from erasing newer work.

expected rev 7WorkConflictError
New engineering guide

Why retries create duplicate issue comments

Designing an idempotent, conflict-safe transaction boundary across five provider APIs.

Read the guide

Honest by design

Know what each provider can do.

Capabilities are data, not scattered documentation. Detect support before an agent proposes an action.

Explore adapter docs
Work SDK provider capability comparison
CapabilityGitHubGitLabLinearJiraAzure
Create and updateSupportedSupportedSupportedSupportedSupported
CommentsSupportedSupportedSupportedSupportedSupported
Custom statesLimitedLimitedSupportedSupportedSupported
Multiple assigneesSupportedLimitedLimitedLimitedLimited
Atomic update guardLimitedLimitedLimitedLimitedSupported

SupportedLimited or not available

Straight answers

Frequently asked.

Is Work SDK a hosted service?

No. It is an open-source TypeScript library that runs in your application. You bring credentials for the trackers you already use.

Can I inspect provider-specific data?

Yes. Normalized entities can retain the raw provider payload for fields that are not part of the portable core.

Does it replace human approval?

No. Work SDK gives approval systems a concrete diff and warnings to evaluate. Your application decides when a human must approve a commit.

Which issue trackers are supported?

Work SDK supports GitHub Issues, GitLab, Linear, Jira Cloud, and Azure DevOps through separate adapters behind one normalized TypeScript API.

Can I add another tracker?

Yes. Adapters implement a compact public contract. The repository runs a shared internal conformance suite for first-party adapters.

Give agents a safer tool

Ship work,
not side effects.

Start with one provider. Keep one API when your stack changes.

$ npm i work-sdk
Get started Star on GitHub