Guidance for coding agents working in this repository.
A monorepo for a Coding Agent sample for Slack, built with Bolt for JavaScript. Each framework lives in its own directory as a standalone sample:
claude-agent-sdk/— built with the Claude Agent SDKopenai-agents-sdk/— built with the OpenAI Agents SDK
Implementations share a structure and user experience, not code. Keep each one obvious on its own, written in its framework's idiom, rather than adding shared helpers.
To install the Slack plugin for your coding agent, follow Claude Code, Codex, Cursor, and Other Coding Agents in the README.
Run these from inside an implementation directory, such as openai-agents-sdk/:
# Run the app (requires .env with the framework's API key; Slack tokens are optional with the CLI)
slack run # via Slack CLI
npm start # directly
# Lint and format (CI runs these on push to main and all PRs)
npm run lint
# Type check (JSDoc + TypeScript validation)
npm run check
# Run tests
npm testES modules with kebab-case filenames, JSDoc types checked by tsc --checkJs, Biome for linting and formatting (single quotes, 2-space indent, 120 line width), and Node's built-in test runner.
No code comments. Make the code explain itself with clear names, tests, or types. Put the reason for a change in the PR description.
.github/ # Shared CI workflows and dependabot config
claude-agent-sdk/ # Claude Agent SDK implementation
openai-agents-sdk/ # OpenAI Agents SDK implementation
CI runs Biome, the type check, and the tests against each directory with a matrix in .github/workflows/lint.yml and .github/workflows/tests.yml. The lint job also checks the root files with the root biome.json, which skips both directories: run claude-agent-sdk/node_modules/.bin/biome check . from the root to do the same. Dependabot watches each directory separately. When adding an implementation, add its directory to both workflow matrices, to .github/dependabot.yml, and to the framework table in the root README.md.
Three layers: app.js -> listeners/ -> agent/.
app.jsstarts Bolt'sAppin Socket Mode and callsregisterListeners(app).app-oauth.jsis the alternative entry point for OAuth over HTTP, where agent slash commands arrive at the manifest'scode_channels.slash_command_url. Bolt handles each event as it arrives, so a long turn never holds up the stop button, an approval click, or another channel.listeners/holds Bolt handlers only, grouped by Slack feature (actions/,commands/,events/). Each sub-module has aregister(app)function.agent/holds everything else: the agents and their prompts, one file per tool underagent/tools/, the turn handling, the sessions and the deps each run gets, and command approvals.
The flow: a mention or direct message outside a code channel runs a small routing agent that either replies in place or calls create_code_channel. Slack seeds the new channel with the request, and that mention starts the coding agent's first turn there, along with the conversation the request came from. Every later message, slash command, and approval in the channel runs a turn of the same session. Messages sent while a turn runs wait and go into the next turn together.
Implementations share structure, not code, so these parts are kept the same by copying them and changing them everywhere at once:
- The seam between
listeners/andagent/. Listeners import only fromagent/index.js, never from the agent framework, solisteners/is the same in every implementation.agent/index.jsexportsanswerRequest,findSession,runTurn,resumeTurn,stopTurn, andendSession. - Framework-free files.
agent/turns.js,agent/context.js,agent/approvals.js,agent/sessions.js,agent/workspace.js,agent/outcome.js, andagent/prompts.jsdon't import the agent framework. The framework lives inagent/agent.js,agent/guardrails.js, andagent/tools/.turns.jscalls onlyrunRequest(prompt, deps), which returns the reply text, andstartRun(history, text, deps)andresumeRun(paused, approved, deps), which return theRunOutcomeinagent/outcome.js. It calls them through its exportedrunsobject, so tests can stand in for them. The paused run is a handleturns.jspasses back without looking inside, so each framework's way of pausing fits behind it. - What the framework side keeps true.
turns.jsrelies on these, so every implementation keeps them:create_code_channelsetsdeps.codeChannelId, andarchive_channelsetssession.archived. Every code channel tool skips its call oncesession.stoppedis set.turns.jscan drop a paused run without resuming it, since the session's history then shows its pending command as not run: the history already records it that way, or the next run answers it that way before anything else. Beyond that,turns.jsonly checks whetherhistoryis empty, to know a turn is the first. - Prompts.
agent/prompts.jsis the same word for word in every implementation. - Tools. Every implementation offers the same tools with the same names, arguments, and descriptions, written with its framework's tool helper. File tools stay inside the clone and can't write into
.git. A tool that throws tells the model what went wrong. - Command approvals.
commandNeedsApproval(command)is plain JavaScript and the same in every implementation, wrapped in the framework's own approval hook. Read-only commands and local git changes run without asking. Anything that runs the repository's code or reaches outside the clone asks first. Commands run without a shell, andsplitCommandinagent/workspace.jssplits a command the same way for the check and the run. On Windows, Node won't start.cmdand.batprograms likenpmwithout a shell, so those don't run there. - Tests. Test files and names mirror each other, and
tests/agent/runs.test.jsdrives real agent runs with a scripted model to cover pausing, resuming, stopping, and running out of turns.tests/helpers.jsfakes the Slack client from the real one's method tree, so a call to a method that doesn't exist fails.
Refer to each implementation's README for its specifics.