What the agent does
In an app like slack-samples/bolt-js-getting-started-app, the agent reads package.json: "type": "module", main and start pointing at app.js, one dependency, @slack/bolt ^5.1.0, resolved by package-lock.json to 5.1.0 with an engines floor of Node 20, and no devDependencies, tests or lint. app.js builds new App with token from SLACK_BOT_TOKEN, socketMode: true and appToken from SLACK_APP_TOKEN, registers app.message('hello', ...), which answers with a section block carrying a button_click button and uses message.user in the text, registers app.action('button_click', ...), which acknowledges and reads body.user.id, and starts the app in an async IIFE on process.env.PORT || 3000. manifest.json grants channels:history, chat:write and im:history, subscribes to message.channels and message.im, and turns socket mode and interactivity on. .github/workflows/dependencies.yml approves and auto-merges Dependabot's patch and minor updates, and AGENTS.md asks for no code comments. .gitignore lists only node_modules/.
The agent moves app.js to src/app.ts and adds tsconfig.json with module and moduleResolution set to NodeNext, since the package is already ESM, target ES2022, strict, rootDir of src, outDir of dist and types of node. package.json gains typescript and @types/node at the major that matches the Node floor as devDependencies, tsx for a dev script that watches src/app.ts, build as tsc, start as node dist/app.js, and main becomes dist/app.js; .gitignore gains dist/. The types ship with @slack/bolt, so no @types package is needed for it. The async IIFE becomes a top-level await app.start(...), which NodeNext allows in an ES module, and the comments in app.js go, as AGENTS.md asks, with the one explanation that mattered moved into the pull request description.
Two listeners need real typing work under strict. The message argument of app.message is a union of every message subtype, and user is not on all of them: a changed, deleted or bot message has no user, so message.user is a compile error. The agent narrows on subtype, which the plain message leaves unset, returning early for the others, which is also the behaviour the original intended since it greets the person who typed hello. The block it sends is typed as KnownBlock[], so a misspelled type or a button without an action_id fails the build. For app.action the agent passes BlockAction as the type argument so body.user.id is known on the body; ack and say take their types from Bolt. process.env.PORT is string or absent, and the port goes to app.start as a number.
The emitted dist/app.js is the check that nothing changed: the agent diffs it against the original app.js and shows that apart from the subtype guard and the removed comments the two are the same statements in the same order. It runs npm install to update the lockfile, npm run build with zero errors, and node --check dist/app.js. Because no workflow runs a build or a test on pull requests, while dependencies.yml merges Dependabot's minor updates of @slack/bolt automatically, the agent adds .github/workflows/ci.yml that runs npm ci and npm run build on every pull request; from then on the auto-merge has a check to require, and a Bolt release that changes a listener's type is caught before it lands.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Convert this Bolt for JavaScript app to TypeScript. Read package.json, package-lock.json, app.js, manifest.json, AGENTS.md and the workflows under .github/workflows first. Move the source to src/app.ts with a strict tsconfig that matches the package's module type and Node floor, add typescript and @types/node as devDependencies, and set up build, start and dev scripts with the compiled output in dist. Type the message listener so it compiles under strict, narrowing on the message subtype rather than casting, and type the action body. Keep the behaviour identical and diff the compiled output against the original to show it. Follow the repository's code style notes. If no workflow builds the code on pull requests, add one that runs npm ci and npm run build. Run the build and open a pull request with the diff and the output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request deletes app.js, adds src/app.ts, tsconfig.json and .github/workflows/ci.yml, and changes package.json, package-lock.json and .gitignore. Its description shows the diff between the compiled dist/app.js and the original app.js, the tsc run with no errors, and the two type narrowings with the Bolt types that required them.
The new ci workflow runs on the pull request itself with npm ci and npm run build, so a reviewer sees the first green build before merging, and the Dependabot auto-merge now has a check that branch protection can require. The run's record keeps the install, the build and the node --check output.
Before merging, a reviewer decides whether the subtype guard should log the messages it skips, whether dev should use tsx or Node's own type stripping, and whether @types/node should track the Node floor or the latest LTS. manifest.json, the scopes and the listeners' behaviour are unchanged.
Run it on every JavaScript service left behind by a TypeScript codebase
A team whose other services are TypeScript sends this body to POST /o/{org}/sessions for each Bolt app still in JavaScript, with the repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than opening a second pull request. Each run reads its own app: a CommonJS package gets module set to match instead of NodeNext ESM, an app with app.event or app.command listeners gets those typed too, and one that already has a test runner gets the tests moved to TypeScript in the same pull request.
The key's webhook_url reports each run the key starts with the pull request in result. Once the build runs on pull requests, an automation on the Project with a schedule trigger each morning and the prompt "for each open Dependabot pull request that bumps @slack/bolt, check out its branch, run the build and say which listener types changed" reads each update that is still waiting on its check; a pull request Dependabot opens fires no github trigger, since bot senders never do, and the automation run has its own max_runs_per_hour cap.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Converting a Bolt app is mostly mechanical except where Bolt's types are stricter than the JavaScript was, and those places are exactly the ones worth finding: a message listener that assumed every message has a user, an action body read without knowing its shape. The agent lets the compiler find them in its own sandbox, fixes each by narrowing rather than casting, and proves the behaviour is unchanged by diffing the compiled output against the original.
The build log, the diff and the first CI run stay with the run and are quoted in the pull request. A team with several Slack apps gets the same conversion per repository, each with its own narrowings and its own first green build.
Frequently asked questions
Why does message.user fail to compile?
Bolt types the message argument as a union of message subtypes, and a changed, deleted or bot message has no user. The original code would have sent an odd greeting on those events; the TypeScript version returns early when subtype is set, which is what the sample meant, and the compiler accepts message.user on the remaining type.
Does the compiled app behave the same?
Yes. The description shows the diff between dist/app.js and the original: the same App options, the same two listeners with the same block and the same reply, and the same start call. The only behavioural change is the early return for messages with a subtype, called out separately.
Why add a CI workflow in a conversion pull request?
The repository's only workflow auto-merges Dependabot's minor and patch updates, with no build to wait on. After the conversion a Bolt release that changes a listener type would break tsc, so the pull request adds a workflow that runs the build on pull requests, which both protects the conversion and gives the auto-merge a check.
Can I skip the build step and run TypeScript directly?
On a recent Node the agent's dev script runs src/app.ts through tsx with a watcher, and the description shows the equivalent with Node's own type stripping. start keeps the compiled dist/app.js so production runs plain JavaScript with no loader, which is what the main field now points at.