Skip to content
← Public packages

@kentcdodds/devin

Start, monitor, and manage Devin sessions, knowledge, playbooks, and schedules via the Devin v3 API

FollowFork

OtherTopics: devin, api, sdk, agents, automation

Version
1.2.0
License
MIT
Published
November 3, 2026
Pinned commit
1ec0fce
Rating
No ratings yet
Forks
0
Adaptation effort
—

README

Agent docs

@kentcdodds/devin

Intent

SDK for the Devin v3 API so Kody can start, monitor, and message Devin sessions and manage the org's knowledge notes, playbooks, schedules, and PR reviews. Transport is one compact authenticated helper against https://api.devin.ai (Bearer secret devinServiceUserKey), scaffolded from Devin's official v3-openapi.yaml.

Deliberately v3 only: legacy apk_ v1/v2 keys return 403 against /v3/*. Fork it if you want your own Devin automation surface: see setup below.

What it does

  • Start a Devin session and follow it (status, messages, PRs, structured output)
  • Per-session helpers use devinId (session.session_id), not sessionId
  • Audit recent org sessions, ACU burn, tags, and insights
  • Manage knowledge notes, playbooks, and scheduled sessions
  • Trigger or check a Devin PR review
  • Call unwrapped Devin endpoints via ./request
  • Find sessions that need a human (blocked on a reply, an approval card, a decision, a deploy check after merge) and finished sessions you can archive

createSession, createPrReview, and generateSessionInsights consume ACUs. terminateSession and the delete helpers are destructive, so confirm intent first. Prefer disabling a schedule over deleting it.

Sessions that need attention

./sessions/needs-attention scans recent sessions (default: updated in the last 30 days, not archived) and sorts the ones that need a person into five groups:

ReasonMeaningSuggested action
approval_pendingAn approval or suggestion card is waiting in the Devin UI (uiOnly: true)ping_owner
needs_human_decisionDevin asks for a product or owner decisionping_owner
awaiting_userDevin is blocked waiting on a reply or ends with a questionreply
deploy_stuckThe PR merged but the session is still waiting on a deploy, health, or ship checkcheck_deploy
staleEvery PR is merged or closed and the session is idle, so it can be archivedarchive

It is read-only and changes nothing in Devin. It reads session status and messages from Devin, and PR merge commits from GitHub through @kentcdodds/github. Large accounts are handled in chunks: if a call runs out of time it returns what it has plus a cursor to continue.

./sessions/archive-stale archives sessions from the stale group. It re-checks each one first and, by default, only previews what it would archive (dryRun defaults to true).

What it can and cannot see:

  • Status-based signals (waiting_for_user, waiting_for_approval) come straight from the Devin API and are reliable.
  • UI-only suggestion cards (environment or repo setup suggestions, reminders) are not exposed by the Devin API. They are only caught when Devin's own message mentions them (for example "my suggestion ... is waiting for your approval"). Treat approval_pending as best effort.
  • Decision, question, and deploy detection reads the wording of Devin's last message, so expect some misses and false positives. Each match includes the sentence that triggered it (evidence) so you can judge quickly.
  • includedInLive (whether the live deployment already contains the merge commit) is only computed when you pass a live commit or a health URL.

The decision action is called ping_owner by default. Pass your own name for it (for example decisionAction: 'ping_alex') if your tooling expects one.

Prerequisites / setup

  1. Save user secret devinServiceUserKey: a v3 service user API key (cog_…) from Devin Settings → Devin API. Approve host api.devin.ai. Grant ImpersonateOrgSessions to the service user's role so sessions can be created as your Devin user (see below).
  2. Persist setting devinOrgId (org-…) in this package's storage (or pass orgId on every helper). Update without republishing via ./settings.
  3. Recommended: persist setting devinCreateAsUserId (user-…, your own Devin user id) via ./settings ({ createAsUserId: 'user-…' }).
  4. For ./sessions/needs-attention and ./sessions/archive-stale: the @kentcdodds/github package with a connected GitHub account (default alias kent, change it with githubAccount) to read PR merge commits.
  5. Agents: see AGENTS.md for import paths and smoke checks.

Default Devin user for new sessions

New sessions are created as the Devin user saved in devinCreateAsUserId, not as the service user. Why: a session created as your user gets your Devin connections, including your Kody MCP and Kody CLI access. Sessions created as the service user do not have those connections and can stall waiting on an MCP sign-in.

The default applies to everything here that starts sessions:

  • createSession (./sessions)
  • createSchedule (./schedules): the schedule's sessions run as that user
  • devinRequest (./request) when it POSTs an object body to /v3/organizations/{org_id}/sessions or /v3/organizations/{org_id}/schedules

Per call:

  • Override: pass createAsUserId: 'user-…' (raw devinRequest body: create_as_user_id: 'user-…').
  • Opt out (service user): pass createAsUserId: null (raw body: create_as_user_id: null).

With nothing saved, behavior matches earlier versions: sessions use the service user. Clear the saved default with ./settings ({ createAsUserId: null }). updateSchedule never applies the default; pass runAsUserId (or null to revert to the service user) to change who an existing schedule runs as. PR reviews (createPrReview) take no user, so they are unaffected.

If you forked this package

  1. Save devinServiceUserKey (user scope) with host api.devin.ai approved.
  2. Set devinOrgId with ./settings ({ orgId: 'org-…' }), or pass orgId per call when working across orgs.
  3. Optionally set devinCreateAsUserId with ./settings ({ createAsUserId: 'user-…' }) to your own Devin user id. Without it, sessions use your service user.
  4. Adopt the fork (or approve secret access), then smoke-test with read-only ./self.

Rename the secret by editing DEVIN_SECRET_NAME and the placeholder in src/lib/client.ts (both live in that one file).

Done when

  • devinServiceUserKey is saved; host and package secret access are approved
  • devinOrgId is set (or you always pass orgId)
  • devinCreateAsUserId is set if sessions should run as your Devin user
  • Read-only whoami (./self) succeeds (auth + RBAC smoke)
  • ./sessions/needs-attention returns a summary with totalScanned matching your recent session count (following nextCursor if one comes back)
Report this listing

Log in to report this listing.