@kody/x
Look up X users and tweets, search recent posts, and preview guarded posts through saved OAuth.
Files
@kody/x
Official X logo (black rounded square, white glyph) from the X brand toolkit. Paths are unmodified. X and the X logo are trademarks of X Corp.
Intent
Give any Kody account reusable, headless X API v2 helpers for user lookup, tweets, recent search, and guarded posting. Auth is the caller’s saved x / x-* OAuth integration (optional app-only bearer for public reads). Identity always comes from the connected account — never a hard-coded profile.
This listing is meant to be forked. After you fork, connect your X app and run ./smoke-test on your copy. Do not treat the live @kody/x integration as yours. Share https://kody.codes/@kody/x.
What it does
- Verify a saved
xOAuth integration and read the connected user - Look up a user by username, read a tweet, list a user’s recent tweets, or search recent posts
- Call uncommon X API v2 routes with
./request - Preview a post or social action with
dryRun: true, then mutate only afterconfirm: true
Do not use this package as a 24/7 bot, a scraping client, or a place to paste access tokens. It does not include encrypted X Chat, Fly sidecars, or any owner-specific infrastructure.
Prerequisites / setup
X is bring-your-own OAuth. There is no built-in Kody X app. Tokens come from the hosted connect page. Never paste a client secret or access token into chat.
- Open X Developer Portal → create a Project and App with User authentication (OAuth 2.0).
- App type: Native App (public / PKCE) or a confidential client with PKCE enabled.
- Callback / redirect URI — register exactly
https://kody.codes/connect/oauth. - Website URL can be
https://kody.codes. - Open this prefilled connect URL while signed in to Kody:
https://kody.codes/connect/oauth?provider=xFirst-time setup also needs X’s authorize and token URLs. Use this complete prefilled URL when the connection does not exist yet:
https://kody.codes/connect/oauth?provider=x&authorizeUrl=https%3A%2F%2Fx.com%2Fi%2Foauth2%2Fauthorize&tokenUrl=https%3A%2F%2Fapi.x.com%2F2%2Foauth2%2Ftoken&apiBaseUrl=https%3A%2F%2Fapi.x.com%2F2&flow=pkce&allowedHosts=api.x.com%2Cupload.x.com&dashboardUrl=https%3A%2F%2Fdeveloper.x.com%2Fen%2Fportal%2Fdashboard&scopes=tweet.read%20tweet.write%20users.read%20offline.access%20like.read%20like.write%20follows.read%20follows.write%20bookmark.read%20bookmark.writeDecoded: authorize https://x.com/i/oauth2/authorize, token https://api.x.com/2/oauth2/token, API base https://api.x.com/2, flow pkce (use flow=confidential&pkce=true if the X app has a client secret), hosts api.x.com + upload.x.com, scopes tweet.read / tweet.write / users.read / offline.access / like.* / follows.* / bookmark.*.
- Paste the Client ID (and Client Secret only for confidential apps) into the Kody form, continue to X, and approve.
- Run the smoke test on the forked package (agents:
AGENTS.md).
Reconnect with https://kody.codes/connect/oauth?provider=x.
Optional app-only bearer
Public reads can use an app-only bearer token. Save it as xBearerToken (never paste the value into chat):
https://kody.codes/account/secrets/new?name=xBearerToken&description=X%20API%20v2%20app-only%20bearer%20token%20for%20optional%20public%20reads&allowedHosts=api.x.com&scope=userOAuth remains the default. Writes always use OAuth.
Multi-account
| Call | Resolves to |
|---|---|
| omit both | integration x |
account: 'work' | integration x-work |
integration: 'x-work' | that exact integration |
Connect more accounts at https://kody.codes/connect/oauth?provider=x-work (same first-time query params, different provider).
Mutation safety
Mutating helpers never write when dryRun: true, and refuse a live write unless confirm: true. Agents: import paths, smoke snippets, and confirm examples live in AGENTS.md.
Done when
x(orx-*) OAuth is connected; hostsapi.x.com/upload.x.comapproved- Smoke test returns
{ ok: true, user: { id, username, name } }without posting - Destructive / posting helpers refuse unless
confirm: true;dryRun: truenever writes
Troubleshooting
- Connect page asks for authorize/token URLs: use the complete first-time URL above.
- HTTP 401 / expired token: reconnect or call
./refresh-oauth-token. - HTTP 403 on writes: add matching write scopes, then reconnect.
- HTTP 429: rate-limited; treat as plumbing-verified for smoke; wait before retrying.
redirect_urimismatch: callback must be exactlyhttps://kody.codes/connect/oauth.