aiagentchat - Implementation Plan

Executive Summary

The aiagentchat project delivers a daemon that monitors Matrix chat rooms and executes Claude Code CLI commands, enabling real-time AI-to-AI communication. The implementation consists of 3 core modules (matrix_client, gateway, daemon), a CLI tool (cchat), and a test suite.

Total Tasks

Agent Roles

Parallel Groups

~650

LOC (app)

External Dep

8 days

Estimated Duration

Key Features

Matrix Synapse integration via matrix-nio client library
3-thread daemon architecture (message receiver, CLI executor, output sender)
Real-time streaming output to Matrix chat
CLI tool (cchat) for sending commands to monitored rooms
Message buffering and rate limiting (2s batching window)
Session management and context persistence
Security: room-based auth, path validation, content filtering

Architecture Overview

Matrix Synapse

↔

MatrixClient

↔

Daemon (3 threads)

↔

Gateway

↔

Claude Code CLI

Component Roles

Component	Responsibility
MatrixClient	matrix-nio wrapper, async event handling, message send/receive
Gateway	Message buffering (2s window), rate limiting, output aggregation
Daemon	3 threads: recv (Matrix→queue), exec (CLI runner), send (queue→Matrix)
CLI Tool (cchat)	Send commands to monitored Matrix rooms
Config	YAML config, environment variables, room-to-agent mapping

Data Flow

User posts message in Matrix room
MatrixClient receives event → MessageReceiver thread
Gateway buffers message (2s window) → enqueue to command queue
CLIExecutor thread picks up command → spawns Claude Code CLI subprocess
Streams output → Gateway buffer → OutputSender thread
OutputSender batches output (2s) → MatrixClient → Matrix room

Phase Timeline

gantt title aiagentchat Implementation Timeline dateFormat YYYY-MM-DD axisFormat %d section Phase 1: Foundation (Seq) Architecture & Protocol (Arch) :a1, 2026-02-06, 1d Matrix Security Setup (Sec) :a2, after a1, 1d Project Init & GitLab (Dev+QA) :a3, after a1, 1d section Phase 2: Core Libs (Group A) Matrix Client (Dev-1) :b1, after a2 a3, 1d Gateway & Buffer (Dev-2) :b2, after a2 a3, 1d Config Module (Dev-1) :b3, after a2 a3, 1d section Phase 3: App Logic (Group B) Daemon Impl (Dev-1) :c1, after b1 b2 b3, 1d CLI Tool (Dev-2) :c2, after b1 b2 b3, 1d Test Suite (QA) :c3, after b1 b2 b3, 1d section Phase 4: Deploy (Seq + Group C) Docker & CI/CD (Dev+QA) :d1, after c1 c2 c3, 1d Deploy & Smoke Test (Dev+QA) :d2, after d1, 1d Security Audit (Sec) :d3, after d1, 1d

Dependency Graph

graph TD A1[1.1 Architecture & Protocol] --> A2[1.2 Matrix Security] A1 --> A3[1.3 Project Init & GitLab] A2 --> B1[2.1 Matrix Client] A3 --> B1 A1 --> B2[2.2 Gateway & Buffer] A1 --> B3[2.3 Config Module] B1 --> C1[3.1 Daemon] B2 --> C1 B3 --> C1 B1 --> C2[3.2 CLI Tool] B2 --> C2 B3 --> C2 A2 --> C3[3.3 Test Suite] B1 --> C3 B2 --> C3 B3 --> C3 C1 --> D1[4.1 Docker & CI/CD] C2 --> D1 C3 --> D1 D1 --> D2[4.2 Deploy & Verify] D1 --> D3[4.3 Security Audit]

Task Details

Phase 1: Foundation (Sequential - 3 days)

Task	Agent	Group	Dependencies	Deliverable
1.1 Architecture & Protocol	Architect	Seq	None	ADR + Protocol spec
1.2 Matrix Security Setup	Security	Seq	1.1	4 Matrix accounts + room + secrets
1.3 Project Init & GitLab	Developer + QA	Seq	1.1	GitLab project + CI skeleton

Phase 2: Core Libraries (Group A - 1 day)

Task	Agent	Group	Dependencies	Deliverable
2.1 Matrix Client	Dev-1	A	1.1, 1.2	matrix_client.py (~120 LOC)
2.2 Gateway & Buffer	Dev-2	A	1.1	gateway.py (~150 LOC)
2.3 Config Module	Dev-1	A	1.1	config.py (~30 LOC)

Phase 3: Application Logic (Group B - 1 day)

Task	Agent	Group	Dependencies	Deliverable
3.1 Daemon Implementation	Dev-1	B	2.1, 2.2, 2.3	daemon/main.py (~200 LOC)
3.2 CLI Tool	Dev-2	B	2.1, 2.2, 2.3	cli/cchat.py (~150 LOC)
3.3 Test Suite	QA	B	1.2, 2.1, 2.2, 2.3	Test suite (70%+ coverage)

Phase 4: Deployment (Sequential + Group C - 3 days)

Task	Agent	Group	Dependencies	Deliverable
4.1 Docker & CI/CD	Developer	Seq	3.1, 3.2, 3.3	Dockerfile + CI/CD + deploy.sh
4.2 Deploy & Verify	Developer + QA	C	4.1	Production deployment
4.3 Security Audit	Security	C	4.1	Security audit report

Agent Workload Distribution

PM

Role: Coordination
Tasks: Overall coordination
Phases: All phases

Architect

Primary: 1.1
Support: Reviews
Phases: 1

Security

Primary: 1.2, 4.3
Support: Reviews
Phases: 1, 4

Developer-1

Primary: 2.1, 2.3, 3.1
Support: 1.3, 4.1, 4.2
Phases: 1, 2, 3, 4

Developer-2

Primary: 2.2, 3.2
Support: 1.3, 4.1, 4.2
Phases: 1, 2, 3, 4

QA

Primary: 3.3
Support: 1.3, 4.1, 4.2
Phases: 1, 3, 4

Module Structure

aiagentchat/ ├── config/ │ ├── __init__.py │ └── config.py # ~30 LOC - YAML config, env vars ├── matrix/ │ ├── __init__.py │ └── matrix_client.py # ~120 LOC - matrix-nio wrapper ├── gateway/ │ ├── __init__.py │ └── gateway.py # ~150 LOC - buffering, rate limiting ├── daemon/ │ ├── __init__.py │ └── main.py # ~200 LOC - 3-thread daemon ├── cli/ │ ├── __init__.py │ └── cchat.py # ~150 LOC - CLI tool for sending commands ├── tests/ │ ├── __init__.py │ ├── test_matrix_client.py # ~100 LOC │ ├── test_gateway.py # ~80 LOC │ ├── test_daemon.py # ~120 LOC │ └── test_integration.py # ~150 LOC ├── config.yaml # Room mappings, agent configs ├── requirements.txt # matrix-nio, httpx, pyyaml ├── Dockerfile ├── docker-compose.yml ├── deploy.sh ├── .gitlab-ci.yml └── README.md # Total Application LOC: ~650 # Total Test LOC: ~450 # External Dependencies: httpx (Matrix API), matrix-nio

Risk Register

Risk	Impact	Mitigation	Owner
Matrix rate limiting (429 errors)	High	2s batching window in Gateway, exponential backoff	Dev-2
Message ordering (race conditions)	Medium	Thread-safe queues, single sender thread per room	Dev-1
CLI process hangs/zombies	High	Timeout enforcement, subprocess cleanup, signal handling	Dev-1
Cross-room data leakage	Critical	Room-based working directories, path validation	Security
Token/secret leakage in logs	Critical	Env vars only, log filtering, no secrets in config.yaml	Security
Matrix connection drops	High	Auto-reconnect logic, sync token persistence	Dev-1
Large message truncation	Medium	Chunking (64KB limit), fallback to file upload	Dev-2
Resource exhaustion (memory)	Medium	Buffer size limits, queue depth monitoring	Dev-2
Concurrent command conflicts	Low	Single-threaded executor per room, queue serialization	Dev-1
Dependency version drift	Low	Pin matrix-nio version, CI dependency checks	QA

Grey Areas / Decisions Required

D1: Message Format

Decision: Use plain text commands with optional markdown formatting for output

Rationale: Simple parsing, human-readable, compatible with all Matrix clients. Markdown for rich output (code blocks, tables).

D2: Session Persistence

Decision: Store session metadata in SQLite (room_id, last_sync_token, active_sessions)

Rationale: Survive daemon restarts, prevent message replay, track session state. Lightweight for MVP.

D3: CLI Timeout

Decision: 300s (5 minutes) default timeout per command, configurable per-room

Rationale: Allow long-running operations (builds, tests), prevent indefinite hangs. User can override in config.yaml.

D4: Multi-User Support

Decision: MVP: Single user per room. Future: Room-based auth with user mapping

Rationale: Simplify Phase 1 implementation. Add user mapping in Phase 2 if needed.

D5: Error Handling

Decision: Send error messages back to Matrix room, log to Loki, emit metrics

Rationale: User visibility (errors in chat), debugging (Loki logs), monitoring (Grafana alerts).

Success Criteria

Daemon starts successfully, connects to Matrix, listens to configured rooms
Commands posted in Matrix room trigger Claude Code CLI execution
CLI output streams to Matrix in real-time (2s batching window)
Session context persists across multiple messages in same room
Room isolation: Commands in Room A do not affect Room B
Graceful error handling: CLI errors appear in chat, daemon continues running
Test coverage 70%+ (unit + integration tests pass in CI/CD)

Source Documents

Solution Document Plan Ask Claude Plan Gemini Plan Codex Plan Draft Plan Codex Review Final Plan (Markdown)