Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• entrypoint.sh
• src/main.ts
• src/agent/setup.ts
• deploy/cloudformation.yml
• src/surface/slack.ts
• src/slack/client.ts

pi-digby is a specialized Slack and Linear bot assistant powered by Amazon Bedrock (specifically Claude Sonnet 4.6) and the pi-agent-core framework. It is designed to operate as an autonomous agent capable of executing shell commands, managing persistent memory across conversations, and integrating with external Model Context Protocol (MCP) servers.

The system is architected to run within a Dockerized environment on AWS ECS Fargate, utilizing Amazon EFS for persistent storage and Slack Socket Mode for secure communication without requiring public endpoints. Sources: CLAUDE.md:1-15, deploy/cloudformation.yml:500-550

System Infrastructure

The infrastructure is defined via AWS CloudFormation and follows a serverless container pattern. The core compute is handled by AWS ECS Fargate, which manages a single Docker container instance.

Visual Infrastructure Map

This diagram illustrates the relationship between the AWS services and the application container.

Key Infrastructure Components

Component	Technology	Purpose
Compute	AWS ECS Fargate	Runs the Node.js application in a managed container.
Storage	Amazon EFS	Provides persistent storage at /data for logs, memory, and tool state.
AI Backend	Amazon Bedrock	Provides the LLM capabilities (Claude 3.5 Sonnet).
Secrets	AWS Secrets Manager	Stores API tokens for Slack, Linear, and search services.
Networking	VPC / Socket Mode	Uses outbound-only WebSocket connections to Slack.

Sources: CLAUDE.md:15-30, deploy/cloudformation.yml:120-150, deploy/cloudformation.yml:540-570

Execution Lifecycle

The application entry point is src/main.ts, which initializes the configuration, starts the Slack client, and sets up event watchers. The lifecycle follows a specific sequence from container boot to event processing.

Bootstrap Sequence

When the container starts, the entrypoint.sh script prepares the environment before launching the Node.js process.

1. Symlink Persistence: Links directories like ~/.pi and ~/.gitconfig to EFS to ensure configuration persists across restarts.
2. MCP Configuration: Seeds the default Model Context Protocol (MCP) configuration if not present.
3. Search Indexing: Runs qmd commands to register and update embedding collections for global and channel-specific memory.
4. Application Launch: Executes node dist/main.js /data.

Sources: entrypoint.sh:1-45, src/main.ts:250-270

Event Handling Flow

Events from Slack or Linear are routed through a per-channel queue to ensure sequential processing and prevent race conditions.

Core Modules and Components

Agent System (src/agent/)

The agent system is built on pi-agent-core and pi-coding-agent. It manages the conversation state and tool execution.

• System Prompting: The buildSystemPrompt function constructs a detailed prompt including environment context, available tools (skills), and user/channel mappings.
• Session Management: Uses SessionManager to persist conversation history into context.jsonl files within the channel directory.
• MCP Integration: Dynamically loads MCP adapters via jiti to allow the agent to use external tools like Exa search.

Sources: src/agent/prompt.ts:15-50, src/agent/setup.ts:110-140

Persistence Layer (src/persistence/)

Persistence is strictly directory-based on the EFS mount:

• Global Memory: MEMORY.md at the root of the workspace.
• Channel State: Each channel has a dedicated folder containing log.jsonl (message history), context.jsonl (LLM session state), and a scratch/ directory for tool operations.

Sources: CLAUDE.md:18-25, src/persistence/memory.ts:15-35

Surface and Transport (src/surface/)

The "Surface" abstraction manages how the agent's output is rendered to the user.

• SlackSurface: Handles streaming updates to Slack messages, including a footer that tracks step count and cost. It converts standard Markdown to Slack's mrkdwn format.
• Message Buffering: Ensures all Slack updates are serialized through an updateChain to maintain message order during streaming.

Sources: src/surface/slack.ts:40-70, src/surface/slack.ts:120-150

Security and Authentication

The system implements a multi-layered security model:

1. Identity: Bedrock authentication is handled via the ECS Task Role (pi-digby-task), eliminating the need for hardcoded AWS credentials.
2. Environment: Tools like bash and edit run directly on the host machine (within the container), with the system prompt warning the agent to be careful with modifications.
3. Secrets Management: Environment variables are injected into the ECS container from AWS Secrets Manager at runtime.

Sources: CLAUDE.md:38-45, deploy/cloudformation.yml:300-330, src/agent/setup.ts:50-65

Conclusion

The pi-digby architecture leverages a serverless containerized approach to provide a persistent, tool-capable agent. By combining the pi-agent-core logic with AWS-managed storage and AI services, it achieves a balance between complex autonomous capabilities and reliable state management.