py-code-agent: An AI Programming Assistant Supporting 100+ Models and Five-Layer Self-Healing Capability

py-code-agent is an AI programming assistant based on the ReAct reasoning loop, designed with a plug-in architecture. It supports over 100 model providers and features an innovative five-layer self-healing mechanism to ensure system stability.

In the AI programming assistant field, most tools are either tied to specific model providers or lack flexible extension mechanisms. py-code-agent breaks this pattern—it is an AI programming assistant based on the ReAct (Reasoning + Acting) reasoning loop, designed with a plug-in architecture. It supports over 100 model providers via LiteLLM and features an innovative five-layer self-healing mechanism to ensure system stability.

The design philosophy of py-code-agent is modularity and extensibility. Its core architecture consists of multiple layers:

• CLI Layer: Provides command interfaces like chat, run, config, plugin, channel websocket
• Core Layer: Includes Agent (ReAct loop), Session, Events, PluginManager
• LLM Layer: Unified access to over 100 providers (OpenAI, Anthropic, Azure, Ollama, etc.) via LiteLLM
• Plugin System: Extensible architecture based on pluggy, supporting four layers of plugin loading (built-in, local, global, PyPI)
• Tools & Channels Layer: File operations, Bash execution, WebSocket, MCP gateway, A2A protocol

Traditional AI assistants often use a single-turn Q&A model, but py-code-agent introduces the ReAct (Reasoning + Acting) reasoning loop. When react.enabled: true is enabled, the Agent follows the "Think → Act → Observe" loop:

1. Thought: The LLM analyzes the current task state and decides the next action
2. Act: Call a tool or generate the final answer
3. Observe: Feed the tool execution result back into the context
4. Repeat: Until task_done is called or the maximum number of rounds is reached

This model allows the Agent to code autonomously—it can write files, run tests, fix errors, and iterate continuously until the task is completed. For example, when asked to "create a Python script that prints the Fibonacci sequence", the Agent will proactively analyze the requirement, write code, verify the output, rather than just returning a code snippet.

The most innovative feature of py-code-agent is its five-layer self-healing mechanism. In plug-in systems, plugin crashes or configuration errors often render the entire system unavailable. This project solves this problem with the following five layers of protection:

Layer	Scenario	Fix Strategy
Layer 1	Hook method crash	Runtime try/except wrapping
Layer 2	Plugin missing hook method	Inject no-op stub
Layer3	Import error (missing dependency package)	Auto pip install and retry
Layer4	Attribute error	Inject missing attribute
Layer5	Tool execute() crash	AST patch source file and reload

This design ensures that even if a plugin has issues, the system can continue to run and even fix the problem automatically. The Layer5 AST patching is particularly innovative—it can modify the source code at runtime and reload it without restarting the entire system.

The plugin system of py-code-agent uses a four-layer loading strategy, with priority from highest to lowest:

1. Built-in Plugins: Core plugins distributed with the package, such as SoulPlugin (loads soul.md personality definition), AgentIdentityPlugin (self-awareness), PlanPlugin (complex task planning)
2. Local Plugins: Project-specific ./.py-code-agent/plugins/ directory
3. Global Plugins: User-level ~/.config/py-code-agent/plugins/ directory
4. Entry Point Plugins: Community plugins distributed via PyPI

Released community plugins include:

• py-code-agent-git: Git status and operations
• py-code-agent-search: Web search via DuckDuckGo
• py-code-agent-mcp-gateway: MCP server connection (supports 10,000+ tools)
• py-code-agent-a2a-gateway: Inter-agent communication (A2A v0.3.0)
• py-code-agent-grep: Code search engine (text + AST)

py-code-agent supports multiple communication channels:

• CLI Channel: Start an interactive terminal via py-code-agent chat, suitable for local development
• WebSocket Channel: Start a service via py-code-agent channel websocket --port 8080, supporting remote access and integration

The WebSocket mode uses a simple JSON message format, making it easy to integrate with other systems. This design allows py-code-agent to be used both as a personal development assistant and deployed as a team service.

py-code-agent introduces a Skill system that supports loading reusable workflows from SKILL.md files and is compatible with Claude Code. The Skill discovery paths are ordered by priority:

• ./.py-code-agent/skills/<name>/SKILL.md
• ~/.config/py-code-agent/skills/<name>/SKILL.md
• ~/.claude/skills/<name>/SKILL.md

This means Skills written for Claude Code can be directly used in py-code-agent, enabling cross-platform reuse of workflows.