What the agent does
The agent reads how the app logs today before replacing it, because Bolt's logger is an interface and not a console. In an app like slack-samples/bolt-js-getting-started-app, package.json is an ES module with one dependency, @slack/bolt ^5.1.0, resolved to 5.1.0 in package-lock.json with @slack/logger 5.0.0 beneath it and an engine requirement of Node 20 or later, and one script, start. app.js constructs App with a bot token, socketMode true and an app token, registers a message listener for hello that replies with a section block and a button, an action listener for button_click, starts on PORT or 3000, and writes one startup line through app.logger.info. manifest.json subscribes to message.channels and message.im with interactivity and Socket Mode on. AGENTS.md asks for no code comments. There are no tests and no lint.
Reading Bolt's source shows where a logger plugs in. App takes logger and logLevel options; without a logger it creates a ConsoleLogger from @slack/logger, which prints lines like [INFO] bolt-app message, and since Bolt 3.4 it hands the same logger to the WebClient and to the receiver, so one object receives Bolt's framework lines, the Web API client's retries and errors, and the Socket Mode client's connection events. The interface is small: debug, info, warn and error taking any arguments, setLevel and getLevel on a LogLevel whose values are the strings error, warn, info and debug, and setName. Those level strings are pino's own level names, which makes the adapter short.
The agent adds pino and writes logger.js. It exports a root pino logger with level from LOG_LEVEL defaulting to info and a service binding, and a createBoltLogger(root) function returning an object that satisfies Bolt's interface: each of the four methods joins string arguments into msg and attaches any object arguments under args, so a Web API error object is kept as JSON rather than stringified; setLevel sets the child's level, getLevel returns it, and setName rebinds name. app.js passes logger: createBoltLogger(root) to App and keeps the startup line. A global middleware registered with app.use logs one record per inbound payload with type from the body, the event or action id when present, team and user from context, and the elapsed milliseconds after await next(), so every message and button click is one JSON line with the same shape. A redact list on the root logger covers token and headers.authorization in case a debug payload ever carries them.
Tests use Node's built-in runner, which Node 20 has, so no framework is added. logger.test.js builds a pino logger on a writable stream that collects lines, wraps it with createBoltLogger, calls info with a string and an object and error with an Error, and asserts each line parses as JSON with the expected level, msg, args and name after setName; a second case calls setLevel('warn') and asserts info writes nothing. package.json gains "test": "node --test". In the sandbox the agent runs npm install and npm test, starts the app with placeholder tokens long enough to show the startup line and the Socket Mode client's connection error as JSON records, since no real workspace is reachable, and opens the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add structured logging to this Bolt for JavaScript app. Read package.json, package-lock.json for the resolved @slack/bolt and @slack/logger versions, app.js, manifest.json, AGENTS.md and README.md first, and read the Logger interface in @slack/logger and the logger and logLevel options in Bolt's App to confirm what the adapter must implement. Add pino and write logger.js exporting a root pino logger with level from LOG_LEVEL defaulting to info, a service binding and a redact list for token and headers.authorization, plus createBoltLogger(root) returning an object with debug, info, warn, error, setLevel, getLevel and setName that joins string arguments into msg and attaches object arguments under args. Pass it as the logger option to App in app.js and add a global middleware with app.use that logs one record per payload with the body type, the event or action id, team and user from context, and elapsed milliseconds after next. Follow AGENTS.md and write no code comments. Add logger.test.js for node --test that checks the JSON shape of info and error records, the name after setName and that setLevel warn silences info, and add a test script. Run npm install and npm test, start the app with placeholder tokens to show the startup line and the connection failure as JSON, then open a pull request that pastes the test output and those records.",
"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
What comes back is a pull request that adds logger.js and logger.test.js and changes app.js, package.json and package-lock.json. The description pastes the node --test output, the startup record as one JSON object with level, time, service, name and msg, and the Socket Mode connection failure as an error record with the error under args, which is what the same app prints as plain text today.
The run's record holds the install, the test run and the short app start. The two listeners, the manifest and the Dependabot workflow are untouched; the listener code reaches the new logger through the logger argument Bolt already passes, with no import.
Before merging, a reviewer decides the production LOG_LEVEL, whether the per-payload middleware should log at info or debug in a busy workspace, and whether the log shipper wants pino's default numeric level or a formatters.level that writes the label.
Run it on every new Slack app
A team that runs several Bolt apps starts one run per repository from its own server: one POST /o/{org}/sessions 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. Each run reads that app's own App options, so an app already on HTTP mode with an ExpressReceiver gets the adapter passed to the receiver too, and a TypeScript app gets the adapter typed against Logger from @slack/bolt.
Afterwards, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "if this pull request adds a console.log or constructs a logger that bypasses logger.js, comment with the line and the logger argument to use instead" keeps every line in the same stream. The trigger adds the pull request after the prompt; only work by an owner, member or collaborator fires 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 useful fact is one line in Bolt's constructor: the logger it is given is also the logger of the Web API client and the receiver, so a correct adapter turns three sources of text into one JSON stream, while a console.log sprinkled through listeners catches none of the framework's own lines. The agent reads the interface in @slack/logger and the option handling in App at the installed version, writes the adapter against them, and tests the record shape.
In its own sandbox the agent runs the tests and starts the app, and the run keeps the records for the pull request. For a team with many Slack apps, each gets its own run and its own pull request with the adapter wired to how that app constructs App.
Frequently asked questions
Do my listeners need to import the logger?
No. Bolt passes logger to every listener and middleware as an argument, and it is the object you gave App, so logger.info inside a listener writes the same JSON through the same pino instance. Only code outside Bolt's call tree imports from logger.js.
Why pino rather than winston or console with JSON.stringify?
pino writes one JSON object per line by default and its level names are the same four strings Bolt's LogLevel uses, so the adapter maps them directly. Any logger could sit behind the adapter; the interface Bolt wants is the four methods plus setLevel, getLevel and setName.
Will the Web API client's errors be structured too?
Yes. Bolt hands its logger to the WebClient and the Socket Mode receiver, so rate-limit retries, API errors and connection events arrive through the adapter as records, with the error object kept under args instead of flattened into a string.
How is the app tested without a Slack workspace?
The tests cover the adapter and the record shape with a pino logger writing to an in-memory stream, which needs no network. The run also starts the app with placeholder tokens for a few seconds, long enough to show the startup record and the connection failure as JSON, which demonstrates the receiver is logging through the adapter.