@kentcdodds/devin
Start, monitor, and manage Devin sessions, knowledge, playbooks, and schedules via the Devin v3 API
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), notsessionId - 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:
| Reason | Meaning | Suggested action |
|---|---|---|
approval_pending | An approval or suggestion card is waiting in the Devin UI (uiOnly: true) | ping_owner |
needs_human_decision | Devin asks for a product or owner decision | ping_owner |
awaiting_user | Devin is blocked waiting on a reply or ends with a question | reply |
deploy_stuck | The PR merged but the session is still waiting on a deploy, health, or ship check | check_deploy |
stale | Every PR is merged or closed and the session is idle, so it can be archived | archive |
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_pendingas 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
- Save user secret
devinServiceUserKey: a v3 service user API key (cog_…) from Devin Settings → Devin API. Approve hostapi.devin.ai. GrantImpersonateOrgSessionsto the service user's role so sessions can be created as your Devin user (see below). - Persist setting
devinOrgId(org-…) in this package's storage (or passorgIdon every helper). Update without republishing via./settings. - Recommended: persist setting
devinCreateAsUserId(user-…, your own Devin user id) via./settings({ createAsUserId: 'user-…' }). - For
./sessions/needs-attentionand./sessions/archive-stale: the@kentcdodds/githubpackage with a connected GitHub account (default aliaskent, change it withgithubAccount) to read PR merge commits. - Agents: see
AGENTS.mdfor 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 userdevinRequest(./request) when it POSTs an object body to/v3/organizations/{org_id}/sessionsor/v3/organizations/{org_id}/schedules
Per call:
- Override: pass
createAsUserId: 'user-…'(rawdevinRequestbody: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
- Save
devinServiceUserKey(user scope) with hostapi.devin.aiapproved. - Set
devinOrgIdwith./settings({ orgId: 'org-…' }), or passorgIdper call when working across orgs. - Optionally set
devinCreateAsUserIdwith./settings({ createAsUserId: 'user-…' }) to your own Devin user id. Without it, sessions use your service user. - 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
devinServiceUserKeyis saved; host and package secret access are approveddevinOrgIdis set (or you always passorgId)devinCreateAsUserIdis set if sessions should run as your Devin user- Read-only
whoami(./self) succeeds (auth + RBAC smoke) ./sessions/needs-attentionreturns a summary withtotalScannedmatching your recent session count (followingnextCursorif one comes back)
Report this listing
Log in to report this listing.