code-agents (Slack v1)

Code Q&A agent for frontend/backend repositories, built on top of Chat SDK and Codex SDK.

Overview

This service receives Slack mentions, synchronizes two local repositories (frontend and backend), asks Codex for an answer in read-only mode, and replies in the same Slack thread.

The architecture is channel-agnostic: Slack is the active adapter in v1, but core logic is isolated so other adapters can be added later.

Tech Stack

• Runtime: Node.js 20+
• Language: TypeScript
• HTTP server: Hono + @hono/node-server
• Channel layer: chat (Vercel Chat SDK)
• Slack integration: @chat-adapter/slack
• Thread state:
  • In-memory state: @chat-adapter/state-memory
  • Optional Redis state: @chat-adapter/state-redis
• Inference: @openai/codex-sdk

Requirements

• Node.js 20+
• codex installed and authenticated (codex login status)
• Slack app configured with webhook/events
• Valid absolute paths for frontend and backend repositories

Configuration

Create a local .env file from the template:

npm install
cp .env.example .env

Required environment variables:

• FRONTEND_REPO_PATH
• BACKEND_REPO_PATH
• SLACK_SIGNING_SECRET
• Slack auth:
  • Single-workspace: SLACK_BOT_TOKEN
  • Multi-workspace OAuth: SLACK_CLIENT_ID + SLACK_CLIENT_SECRET (+ SLACK_ENCRYPTION_KEY)

Common optional variables:

• BOT_USERNAME
• PORT
• REDIS_URL
• CODEX_MODEL
• CODEX_REASONING_EFFORT

Run

Development:

npm run dev

Type-check:

npm run check

Build:

npm run build

Runtime Behavior

1. The bot responds to Slack mentions.
2. On the first mention in a thread, it subscribes to that thread.
3. In subscribed threads, follow-up messages must still mention the bot.
4. Before every answer, it synchronizes both repos from main:
   • git fetch origin --prune
   • git checkout main
   • git pull --ff-only origin main
   • git rev-parse HEAD
5. Codex runs in read-only mode against local repositories.
6. User-facing answers are in Spanish and avoid code snippets/blocks, file references, and sync metadata.
7. While processing, Slack status text is updated through staged/rotating progress messages.

HTTP Endpoints

• Healthcheck: GET /health
• Slack webhook: POST /api/webhooks/slack
• Slack OAuth callback (multi-workspace only): GET /api/slack/install/callback

Project Structure

• src/server: HTTP/webhook entrypoints
• src/bot: channel event handlers
• src/core: orchestration and response policy
• src/repos: repository sync services
• src/inference: Codex client and prompts
• src/context: prompt context builders

Extending to New Adapters

To add another channel adapter:

1. Register the adapter in src/bot/chat.ts.
2. Add its webhook entrypoint in src/server.
3. Reuse QAOrchestrator from src/core.