What the agent does
The agent first finds where interactions are routed, because that is where modal submissions are being dropped today. On KevinNovak/Discord-Bot-TypeScript-Template, package.json pins discord.js at ^14.22.1 in an ES module project, and src/models/bot.ts has one onInteraction method: a CommandInteraction or AutocompleteInteraction goes to commandHandler.process, a ButtonInteraction goes to buttonHandler.process, and every other interaction type falls off the end of the if. Buttons are the closest existing pattern. src/buttons/button.ts declares a Button with ids, a deferType, two guard flags and execute; src/events/button-handler.ts rate-limits by user from Config.rateLimiting.buttons, looks the button up by intr.customId, defers, builds EventData and calls it. src/start-bot.ts collects commands, buttons, reactions and triggers in arrays marked with TODO comments and passes one handler for each into new Bot(...).
It adds the modal path in that shape and adds nothing the template would not have written itself. A src/modals/modal.ts declares Modal with ids, a ModalDeferType and execute(intr: ModalSubmitInteraction, data: EventData). A ModalHandler in src/events/ mirrors the button handler line for line: ignore bots, take from a RateLimiter built from a new rateLimiting.modals block, find the modal by custom id, defer through InteractionUtils, whose deferReply and send signatures already accept ModalSubmitInteraction, then execute. bot.ts gains a third branch for modal submissions and a constructor argument, and start-bot.ts gains a modals array with the same TODO comment. The new block goes into config/config.example.json; the real config/config.json is ignored by .gitignore and loaded with require, so the pull request tells whoever deploys to add the block there too, or the handler's constructor will throw on the missing key.
The sample is where the one real trap sits. A modal has to be the first response to an interaction, and CommandHandler defers the reply before execute whenever a command's deferType is PUBLIC or HIDDEN. So the sample /feedback command is declared with CommandDeferType.NONE and calls intr.showModal(...) itself, building the form from ModalBuilder, TextInputBuilder and an ActionRowBuilder. Its name and description go through Lang.getRef into src/commands/metadata.ts with their localization maps, and the modal's title, field label and the confirmation embed go into lang/lang.en-US.json and lang/lang.en-GB.json, since the template keeps every user-facing string in those files. The submit side reads the field with intr.fields.getTextInputValue and answers with an embed from Lang.getEmbed.
Tests follow the existing ones under tests/, which build Discord objects with mockDeep in tests/builders/discord-builders.ts and mock InteractionUtils. The agent adds a modal-submit builder, a handler test (unknown id ignored, bot user ignored, rate-limited user ignored, known id deferred and executed) and a command test asserting that showModal is called and deferReply is not. It copies the three *.example.json files in config/ to their real names inside the sandbox so the modules load, then runs npm run lint, npm run format, npm run build and npm test. It does not run npm run commands:register: that needs the bot's token, which the run does not have.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add modal support to this discord.js bot, following the way buttons are built. Read CLAUDE.md, package.json, src/models/bot.ts, src/start-bot.ts, src/buttons/button.ts, src/events/button-handler.ts, src/commands/command.ts, src/events/command-handler.ts, src/commands/metadata.ts, src/utils/interaction-utils.ts, config/config.example.json, lang/lang.en-US.json and the tests under tests/ first. Add a Modal interface in src/modals, a ModalHandler in src/events that mirrors ButtonHandler (bot check, per-user rate limit from a new rateLimiting.modals block in config.example.json, lookup by custom id, defer, execute), a branch for ModalSubmitInteraction in Bot.onInteraction and a modals array in start-bot.ts. Add a sample /feedback chat command that opens a modal with one paragraph field and a modal that answers with a confirmation embed. The command must use CommandDeferType.NONE and call showModal itself, because a modal cannot follow a deferred reply. Put every string in the lang files and the command in metadata.ts. Add test builders and tests for the handler and the command. Copy the example config files to their real names locally without committing them, then run npm run lint, npm run format, npm run build and npm test. Do not register commands with Discord. Open a pull request that says what to add to config.json and to run commands:register after merging.",
"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
A pull request with src/modals/ (the interface, an index and the feedback modal), src/events/modal-handler.ts and its export, the new branch in src/models/bot.ts, the wiring in src/start-bot.ts, the /feedback command with its entry in src/commands/metadata.ts, the strings in both lang files, the rateLimiting.modals block in config/config.example.json, and the builders and tests. Its description quotes the output of the four npm scripts and lists the two steps a person has to take after merging: add the block to the deployed config.json, and run npm run commands:register so Discord learns about /feedback.
A reviewer checks the custom ids first, since the handler matches on them and a typo means a submission that silently does nothing. They check that no command which opens a modal has a deferType other than NONE, and that the handler logs an unknown id the way CommandHandler logs an unknown command instead of returning quietly as ButtonHandler does, which the pull request calls out as a deliberate difference. The form itself can only be seen in a Discord client, so the last check is a person running /feedback on a test server.
Run it on every Linear issue labelled bot-form
Once the handler exists, each new form is a small change: one modal class, one command or button that opens it, a few strings. In the console, add an automation on the bot's Project with a linear trigger on linear.issue.labeled and the label bot-form, and a prompt that says to add the form the issue describes using the Modal interface and the lang files. The issue arrives after the prompt as the event, so the fields and wording come from whoever wrote it. A person in your Rush org has to apply the label; a label set by an app integration does not fire.
The automation's own limit, its max runs per hour, decides how many of these start in an hour; an issue past it gets a run that waits as queued. Each run opens its own pull request on its own branch, so three forms asked for in one afternoon are three reviews, not one tangled diff.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
The template's value is its conventions, and a modal bolted on outside them is a second way of doing things. The agent reads the button path end to end in a fresh sandbox, copies its structure, and then runs the same four scripts a contributor would, with the complete output of each kept in the run's record. A reviewer can open that record and see tsc and vitest pass on the exact tree in the pull request.
It also avoids borrowing anyone's bot token. The config files that hold client.token are ignored by git and never reach the sandbox, so the run works from the example files and stops short of Discord. Someone who does want the agent to register commands on a test application can put a token in the Project as a secret and say so in the prompt; nothing in this request assumes it.
Frequently asked questions
Why does the sample command not defer its reply?
Discord accepts a modal only as the first response to an interaction. CommandHandler defers before execute for PUBLIC and HIDDEN commands, and a showModal after that is rejected. Declaring the command with CommandDeferType.NONE leaves the first response free for the modal.
Can a button open a modal too?
Yes, with the same rule. A Button whose deferType is ButtonDeferType.NONE can call showModal in its execute. The pull request's sample uses a slash command because the template registers no buttons yet.
Does the agent need my bot token?
No. Building, linting and the vitest suite run without one, and the tests replace Discord objects with deep mocks from vitest-mock-extended. Only npm run commands:register talks to Discord, and the request tells the agent to leave that to you.
Will this work with sharding and clustering turned on?
The change does not touch src/start-manager.ts or the controllers. Interactions arrive on whichever shard owns the guild and go through the same Bot.onInteraction, so the modal branch behaves the same in every mode the template starts in.
More discord.js jobs
The same job on other stacks
- Add a Modal to a Slack Bolt App (Slack Bolt)