$ show zhayujie/CowAgent
CowAgent is a production-grade multi-agent AI assistant platform that routes messages from 12+ IM channels (WeChat, Feishu, Telegram, DingTalk, Slack, Discord, QQ, WeCom, web console, desktop Electron app) through a modular agent core. The core implements planning, tool use (bash, file editing, browser, web search, MCP, sub-agent delegation, scheduler, memory, vision), three-tier memory with vector embeddings and markdown-aware chunking, knowledge base management, skill system with SKILL.md manifests and a skill hub, self-evolution (idle-conversation review loop), and multi-agent team orchestration with peer transport. The architecture is a modular monolith: channel adapters normalize messages into a unified ChatMessage, the Bridge dispatches to per-agent/session model resolution, the Agent protocol (Task/AgentResult/AgentAction) drives the execution loop with streaming, cancellation, and steering, and all state persists to SQLite with incremental migration. Key entry points are app.py (startup orchestration), cli/cli.py (daemon lifecycle), channel/web/web_channel.py (HTTP API and SSE streaming), and the desktop Electron client (React/TypeScript with Zustand stores). External dependencies include LLM APIs (OpenAI, Claude, Gemini, DeepSeek, etc.), IM platform webhooks/SDKs, optional voice TTS/ASR providers, and MCP servers. The codebase demonstrates strong engineering practices with extensive regression tests (200+ test files), atomic file writes, thread-safe context propagation via ContextVar, and security guards for credential paths and SSRF.
The LLM identified 10 files worth highlighting for reuse:
A singleton decorator that exposes __wrapped__ and new_instance() for bypassing the singleton constraint. Demonstrates non-obvious Python metaprogramming to allow controlled multi-instance creation while maintaining a default singleton pattern.
A cross-tool credential-path guard that blocks access to .env files, /proc/*/environ, and symlink-resolved sensitive paths. Used by edit/read/write tools to prevent credential leakage. Self-contained and reusable in any file-access tool.
Defines soft exit-code semantics for common Unix commands (grep, find, diff) where exit code 1 is informational rather than an error. Encapsulates bash-specific knowledge into a reusable predicate, improving agent reliability when interpreting command results.
Provides fuzzy-match utilities (find_match_spans, reindent_replacement, strip_line_number_prefixes) used by both write and edit tools for precise file editing with fallback to fuzzy matching. Handles BOM/line-ending preservation and reindent re-anchoring. A single source of truth for counting vs replacing.
Implements IANA timezone-aware cron evaluation with DST handling. Parses cron expressions and computes next run times relative to a specified timezone. Self-contained and reusable for any scheduling system that needs timezone-aware recurrence.
A markdown-aware text chunker that splits documents by heading structure with tail-folding and version-tracked algorithm. Produces chunks suitable for embedding and retrieval. Demonstrates non-obvious handling of markdown hierarchy and version migration for index rebuilds.
Uses ContextVar to propagate agent/user/session/run identity through thread pools without leaking. Provides identity_scope, submit, and wrap for safe context management. Reusable in any multi-threaded application that needs scoped identity.
A cancel token registry using threading.Event for per-request and per-session cancellation. Supports scoped cancellation without global state. Self-contained and reusable for any async or threaded system needing cooperative cancellation.
Implements PKCE authorization code flow using only stdlib HTTP, with token storage in ~/.cow/mcp_oauth.json. Handles pending auth expiry (600s TTL) and token refresh. Self-contained and reusable for any CLI or desktop app needing OAuth with MCP servers.
A generic Zustand store factory for document editing with dirty tracking, mtime-lock conflict detection, discard/overwrite confirm prompts, and editor registry for navigation guard. Demonstrates a reusable pattern for managing unsaved changes in a React app.