All jobs

Add an App Home Tab to a Bolt for JavaScript Slack App

Yes. An agent enables the Home tab in manifest.json, subscribes your Bolt app to app_home_opened, publishes a Block Kit home view from app.js and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the app and its manifest together, because an App Home is half code and half configuration. In a project like slack-samples/bolt-js-getting-started-app, app.js creates an App in Socket Mode from SLACK_BOT_TOKEN and SLACK_APP_TOKEN, listens for messages containing hello with app.message, replies with a section block and a Click Me button whose action_id is button_click, handles that action with app.action, and starts on PORT or 3000. manifest.json has app_home.home_tab_enabled set to false and messages_tab_enabled to true, bot scopes channels:history, chat:write and im:history, bot events message.channels and message.im, interactivity and Socket Mode on. package.json depends on @slack/bolt 5.1 as an ES module with a start script only; there are no tests and no lint, and AGENTS.md asks for no code comments, with the reason for a change in the pull request instead.

Two manifest edits come first: home_tab_enabled becomes true, and app_home_opened joins bot_events, since Slack sends the event only to apps subscribed to it. No new scope is needed for views.publish. Because this app was created from the manifest file, the file alone changes nothing in a workspace that already exists; the pull request says that the reader pastes the new manifest into the app's configuration page, or applies it with the Slack CLI, before the event arrives.

In app.js the agent adds app.event('app_home_opened', ...) that returns early unless event.tab is home, so opening the Messages tab does not republish, then calls client.views.publish with user_id: event.user and a view of type home. The blocks are a header, a section that greets the user by <@id>, and an actions block with one button whose action_id is home_button_click, and a matching app.action handler acknowledges it and posts a message, mirroring the existing button_click pattern so the two read the same. The publish call sits in a try/catch that logs through app.logger, the logger the file already uses. The blocks live in a small function so the same view can be republished after the button is pressed.

The sandbox has no Slack workspace, so the agent cannot open the Home tab to see the view. What it can check, it does: node --check app.js, npm install and a node app.js start that fails only on the missing tokens, JSON validity of the manifest, and the view payload against the Block Kit limits (a header under 150 characters, an actions block with its elements). It states in the pull request that the live check is the reviewer's, and lists the three clicks that make it: apply the manifest, reinstall if prompted, open the app's Home tab.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add an App Home tab to this Bolt for JavaScript app. Read app.js, manifest.json, package.json, README.md and AGENTS.md first. In manifest.json set features.app_home.home_tab_enabled to true and add app_home_opened to settings.event_subscriptions.bot_events. In app.js add an app.event listener for app_home_opened that returns unless event.tab is home, then calls client.views.publish with user_id set to event.user and a home view containing a header, a section that greets the user, and an actions block with one button, with the publish wrapped in try and catch that logs through app.logger. Add an app.action handler for that button that acknowledges and posts a reply, in the style of the existing button_click handler, and build the view in a function so it can be republished. Follow AGENTS.md: no code comments. Run node --check app.js, npm install and node app.js to confirm it fails only on the missing tokens, and validate the manifest JSON. Open a pull request that explains the manifest change must be applied in the Slack app configuration and lists the steps to see the Home tab.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. 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.
  2. 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.
  3. 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

What comes back is a pull request that changes manifest.json and app.js only. The description explains each manifest field it changed and why app_home_opened must be subscribed, shows the blocks the home view publishes, and gives the steps a reviewer follows to see it: apply the manifest on the app's configuration page, reinstall the app if Slack asks, start the app with both tokens set, and open its Home tab.

The run's record keeps the syntax check, the install, the start attempt and the manifest validation, and it says plainly that no view was published during the run because the sandbox holds no workspace tokens.

Before merging, a reviewer runs the app against a development workspace, opens the Home tab, presses the button, and decides whether the view should show something live, such as the user's recent messages to the bot, which is a follow-up the pull request names.

Run it on every new Slack app from the sample

A team that starts each internal Slack app from this sample can run this once per repository from its own server: one POST /o/{org}/sessions per repository, each with that 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 a second pull request.

After that, an automation on the Project with a github trigger on pull_request.opened and the prompt "if this pull request adds an event or action handler to app.js, check manifest.json subscribes to it and lists the scope it needs, and fix the manifest on this branch if not" catches the mismatch that breaks Slack apps most often. The trigger puts the pull request after the prompt; only pushes by an owner, member or collaborator fire it, never a fork's.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The usual failure with an App Home is not the code but the configuration: the listener is right and nothing happens because the Home tab is off or the event is not subscribed. The agent changes the manifest and the code in one pull request, with the dependency between them written down, so the reviewer applies both rather than discovering the gap in a workspace.

The sandbox keeps what was checked and what was not. The pull request can say that app.js parses, starts and stops at the missing tokens, and that the view payload is within Block Kit's limits, while being explicit that the live publish is a reviewer step, which is more useful than a claim the run could not back.

Frequently asked questions

Does the Home tab need a new OAuth scope?

No. views.publish works with the bot token the app already has; what it needs is the Home tab enabled and the app_home_opened event subscribed, both of which are manifest changes. The agent changes those two fields and nothing else in the scopes list.

Why does the handler check event.tab?

app_home_opened fires for the Messages tab as well as the Home tab. Without the check the app would publish a home view every time someone opens a direct message with it, which is wasted calls and, at scale, rate limits.

Why can't the agent show me the Home tab?

The sandbox has no Slack workspace or tokens, and the agent never asks for yours. It verifies the code parses and starts, and that the manifest is valid, then lists the exact steps for you to see the view in a development workspace.

Will it add comments to app.js?

No. The sample's AGENTS.md says code should explain itself and the reason for a change belongs in the pull request, so the agent names its functions clearly and puts the explanation in the description.

More Bolt for JavaScript jobs

More jobs like this: Hand off a long task

Keep reading