Coding Agent
Relevant source files
The following files were used as context for generating this wiki page:
The Coding Agent is an automated system designed to handle software development tasks within the Recoup API repository. It functions as an AI-driven contributor capable of performing repository operations, managing Pull Requests (PRs), and communicating across multiple platforms such as Slack, GitHub, and WhatsApp. The agent utilizes a unified adapter pattern to interact with these external services and maintains state through a Redis-backed persistence layer.
Sources: README.md:129-145, lib/coding-agent/bot.ts:16-43
Architecture and Core Components
The Coding Agent is built on a modular architecture that separates platform-specific communication (adapters) from the core logic and state management. It is implemented as a singleton bot instance that registers itself within the Chat SDK.
Bot Configuration
The agent is initialized with a variety of adapters that allow it to "listen" and "speak" on different platforms.
- SlackAdapter: Connects to Slack via bot tokens and signing secrets to handle events, mentions, and interactivity.
- GitHubAdapter: Manages repository-level operations including file trees, submodules, and PR management.
- WhatsAppAdapter: An optional adapter for mobile-based interaction.
Sources: lib/coding-agent/bot.ts:16-52, README.md:139-145
State Management
State for the coding agent, including thread status, run IDs, and PR references, is persisted in Redis using the ioredis state adapter. This ensures that the agent can maintain context across asynchronous operations and platform-to-platform transitions.
Sources: README.md:145, lib/coding-agent/tests/bot.test.ts:74-84
Request Flow
The following diagram illustrates how a request from a communication platform like Slack is processed by the agent and eventually results in a code change.
API Endpoints and Webhooks
The Coding Agent exposes specific endpoints to receive external triggers and report back on the status of ongoing tasks.
Platform Webhooks
The agent uses a dynamic route segment to handle various platform webhooks through a single entry point.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/coding-agent/[platform] | Handles incoming webhooks from Slack (Events API), GitHub, or WhatsApp. |
GET | /api/coding-agent/[platform] | Often used for platform challenge verifications (e.g., Slack url_verification). |
Sources: app/api/coding-agent/[platform]/route.ts:1-14, README.md:151-160
Callback Mechanism
When a coding task (often running in a sandbox via Trigger.dev) completes, it notifies the API via a callback. This callback must be validated against a strict schema to ensure the integrity of the updated state.
Sources: lib/coding-agent/tests/validateCodingAgentCallback.test.ts:6-48, README.md:162-166
Operational Workflow and Git Standards
Coding agents (including Claude Code and OpenCode) must adhere to a strict Git workflow to maintain repository stability.
Git Rules
- Branching: All work must be performed on feature branches. Direct pushes to
mainortestare strictly forbidden. - Synchronization: Before starting, agents must sync the
testbranch withmain. - Pull Requests: PRs must be opened against the
testbranch, notmain. - Approvals: PRs require explicit user approval before merging; agents cannot merge autonomously.
Sources: CLAUDE.md:7-17, AGENTS.md:7-17
Implementation Example: Callback Validation
The system validates the status of tasks via a specialized validator that checks for specific states such as pr_created, no_changes, failed, or updated.
// Example of a valid pr_created payload
{
threadId: "slack:C123:1234567890.123456",
status: "pr_created",
branch: "agent/fix-bug-1234",
prs: [
{
repo: "recoupable/recoup-api",
number: 42,
url: "https://github.com/recoupable/recoup-api/pull/42%22%2C
baseBranch: "test"
}
]
}
Sources: lib/coding-agent/tests/validateCodingAgentCallback.test.ts:6-21
Conclusion
The Coding Agent acts as a bridge between communication platforms and the codebase, enabling automated yet controlled development cycles. By enforcing strict Git workflows and utilizing a modular adapter-based architecture, the system ensures that AI-driven contributions are traceable, validated, and integrated through standard review processes.