Architecture
gitAgent is the intermediary layer between Explorer user interface (UI) requests and Git command execution, routed through Ploinky AgentServer over Model Context Protocol (MCP).
Component Overview
| Component | Location | Role |
|---|---|---|
| Model Context Protocol contract declaration | gitAgent/mcp-config.json |
Declares all Git tools, command entrypoint, schemas, and per-tool TOOL_NAME. |
| Wrapper command entrypoint | gitAgent/tools/git_tool.sh |
Starts a Node process for each tool invocation. |
| Tool dispatcher | gitAgent/tools/git_tool.mjs |
Parses Model Context Protocol envelope data, validates args, resolves tool operation, and emits JSON results. |
| Git execution service | gitAgent/lib/git-service.mjs |
Composes focused operation modules from gitAgent/lib/git/; command execution, validation, working tree operations, stash/conflict handling, remote operations, and identity management stay in separate files. |
| GitHub auth bridge | gitAgent/lib/github-auth.mjs |
Handles device flow, token persistence, and auth status operations for remote Git actions. |
| Explorer user interface plugin channel | gitAgent/IDE-plugins/git-tool-button/ |
Injects Git interface components in Explorer and calls gitAgent tools via MCP. |
Runtime Boundary
AgentServer executes configured tool commands from mcp-config.json. For this agent, the command path is tools/git_tool.sh. The wrapper delegates behavior to git_tool.mjs, which resolves tool logic and forwards execution to service functions.
{
"name": "git_status",
"command": "tools/git_tool.sh",
"cwd": "workspace",
"env": {
"TOOL_NAME": "git_status"
}
}Intermediary Guarantee
Explorer never needs to execute raw shell Git commands directly. It calls MCP tools and receives normalized responses. This separation keeps Git process control, path security, and auth behavior centralized in the agent.
The architecture goal is operational control and contract stability, not replacing Git itself and not embedding Git runtime logic inside Explorer UI code.