# 0xk212/wormgpt_agent architecture

> Architecture diagram of the GitHub repository 0xk212/wormgpt_agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0xk212/wormgpt_agent
- Repository: https://github.com/0xk212/wormgpt_agent

## Overview

1. **Repo shape: single-entrypoint agent**
   This repository is essentially a one-file Python application centered on `xgpt_agent.py`. The README describes the file as the “Core Intelligence Module,” so the architecture is likely a monolithic CLI agent rather than a multi-service system.

2. **Primary runtime boundary**
   The agent runs locally in a terminal on **Windows, Linux, or Termux**. The main boundary is between the local interactive process and external systems it talks to: the OS shell, the network, and optionally Docker.

3. **User interaction flow**
   The top-level flow is interactive:
   - user launches `python xgpt_agent.py`
   - user selects an OS profile
   - user provides an API key
   - user enters an objective
   - the agent executes commands and streams results back in real time

4. **Command execution subsystem**
   The core function is autonomous command orchestration. The agent appears to accept high-level goals, translate them into shell actions, and run them through the host environment’s command interface, with behavior adapted to the selected platform profile.

5. **Live output and feedback loop**
   A major architectural feature is **live streaming of command output**. That implies a tight execution loop where command results are immediately surfaced, then parsed to decide the next action. For an architecture diagram, this is the central control loop.

6. **Analysis / decision layer**
   The README describes “neural analysis” and “intelligent parsing” of results. Practically, this is the decision-making layer that consumes command output and determines whether to continue, change tactics, or stop. It sits between execution and the next command generation step.

7. **Platform abstraction boundary**
   The tool explicitly supports **Windows CMD**, **Linux Bash**, and **Termux**. That suggests a platform adapter layer or conditional execution paths inside the single script, rather than separate binaries. The OS profile selection at startup likely determines command syntax and environment checks.

8. **Specialized diagnostic commands**
   Built-in slash commands such as `/sysinfo`, `/netinfo`, `/tools`, `/os`, `/help`, and `exit` form a separate control path from autonomous task execution. These are operator-facing diagnostics and introspection commands, not part of the agent’s main goal-oriented loop.

9. **Security layer**
   The README claims **AES-GCM encryption** and **HMAC signature verification**. Architecturally, this means data exchanged with whatever external service backs the “AI” functionality is protected by confidentiality and integrity checks. The key management and session handshake are important boundaries to show in a diagram.

10. **External dependency / AI backend**
    The mention of an API key and encrypted inbound/outbound data implies the agent depends on an external remote service for intelligence or orchestration decisions. That service is not present in the repo, so the Python script is the local controller and the remote API is the decision backend.

11. **Optional sandbox path**
    Docker is described as an optional “sandbox mode” for untrusted commands. This introduces a second execution boundary: instead of running commands directly on the host, the agent can route them into an isolated container. That is a key architectural control for any diagram.

12. **Operational dependency set**
    The documented Python dependencies are minimal: `requests` for network/API communication and `pycryptodome` for cryptography. That reinforces that the repository is a lightweight controller with networking and crypto support, not a large framework.

13. **What to draw as the main components**
    For an accurate architecture diagram, the main boxes are:
    - interactive CLI entrypoint
    - OS/profile selector
    - authentication/session setup
    - command planner / decision loop
    - shell command executor
    - live output streamer
    - crypto/auth layer
    - optional Docker sandbox
    - external AI/API service

14. **Overall architecture summary**
    This is a single-process, terminal-driven autonomous agent that converts user goals into OS-specific shell actions, streams the results, and iterates based on analyzed output. Its main architectural concerns are platform adaptation, remote API communication, cryptographic protection, and optional isolation for command execution.

Main entry points: [`xgpt_agent.py`](https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py) (Decision loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local agent"]
  node_user(("User<br/>operator"))
  node_cli["CLI entrypoint<br/>python script<br/>[xgpt_agent.py]"]
  node_profile["Profile setup<br/>os adapter<br/>[xgpt_agent.py]"]
  node_auth["Session setup<br/>api auth<br/>[xgpt_agent.py]"]
  node_diag["Diagnostics<br/>slash commands<br/>[xgpt_agent.py]"]
  node_objective["Objective input<br/>task prompt<br/>[xgpt_agent.py]"]
  node_planner{{"Decision loop<br/>agent core<br/>[xgpt_agent.py]"}}
  node_crypto["Crypto layer<br/>aes-gcm+hmac<br/>[xgpt_agent.py]"]
  node_executor["Command runner<br/>shell orchestration<br/>[xgpt_agent.py]"]
  node_stream["Live output<br/>streaming feedback<br/>[xgpt_agent.py]"]
end

subgraph group_external["External systems"]
  node_adapter["Platform bridge<br/>env adapter"]
  node_host["Host shell<br/>os shell"]
  node_sandbox[("Docker sandbox<br/>isolated runtime")]
  node_api["AI backend<br/>remote service"]
end

node_user -->|"launches"| node_cli
node_cli -->|"selects"| node_profile
node_cli -->|"prompts"| node_auth
node_cli -->|"collects"| node_objective
node_cli -.->|"routes"| node_diag
node_objective -->|"feeds"| node_planner
node_diag -.->|"bypasses"| node_planner
node_planner -->|"secures"| node_crypto
node_crypto -->|"sends"| node_api
node_api -->|"returns"| node_planner
node_planner -->|"issues"| node_executor
node_executor -->|"adapts"| node_adapter
node_adapter -->|"runs on"| node_host
node_executor -.->|"optionally routes"| node_sandbox
node_host -->|"emits"| node_stream
node_sandbox -->|"emits"| node_stream
node_stream -->|"feedback"| node_planner

click node_cli "https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py"
click node_profile "https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py"
click node_auth "https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py"
click node_diag "https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py"
click node_objective "https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py"
click node_planner "https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py"
click node_crypto "https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py"
click node_executor "https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py"
click node_stream "https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_user,node_cli,node_profile,node_auth,node_diag,node_objective,node_planner,node_crypto,node_executor,node_stream toneBlue
class node_adapter,node_host,node_sandbox,node_api toneAmber
```

## Components

### Local agent

Single-process terminal controller in xgpt_agent.py

- **User**: operator · Launches the agent, selects profile, enters key and objective
- [CLI entrypoint](https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py): python script · Main interactive process in xgpt_agent.py · `xgpt_agent.py`
- [Profile setup](https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py): os adapter · Chooses Windows CMD, Linux Bash, or Termux behavior · `xgpt_agent.py`
- [Session setup](https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py): api auth · Collects API key and prepares the secure session · `xgpt_agent.py`
- [Diagnostics](https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py): slash commands · Handles /sysinfo, /netinfo, /tools, /os, /help, and exit · `xgpt_agent.py`
- [Objective input](https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py): task prompt · Captures the user goal for autonomous execution · `xgpt_agent.py`
- [Decision loop](https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py): agent core · Analyzes command output and chooses the next action · `xgpt_agent.py`
- [Crypto layer](https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py): aes-gcm+hmac · Encrypts and verifies agent communication · `xgpt_agent.py`
- [Command runner](https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py): shell orchestration · Builds and dispatches shell commands · `xgpt_agent.py`
- [Live output](https://github.com/0xk212/wormgpt_agent/blob/main/xgpt_agent.py): streaming feedback · Surfaces command output in real time · `xgpt_agent.py`

### External systems

Host environment, sandbox, and remote backend

- **Platform bridge**: env adapter · Maps execution to host-specific shell syntax and checks
- **Host shell**: os shell · Runs commands on Windows, Linux, or Termux
- **Docker sandbox**: isolated runtime · Optional container boundary for untrusted commands
- **AI backend**: remote service · External intelligence service reached with an API key

## Connections

- User → CLI entrypoint: launches · Starts the terminal agent
- CLI entrypoint → Profile setup: selects · Chooses the runtime profile
- CLI entrypoint → Session setup: prompts · Requests API key and prepares session
- CLI entrypoint → Objective input: collects · Accepts the user goal
- CLI entrypoint → Diagnostics: routes · Handles operator commands separately from task execution
- Objective input → Decision loop: feeds · Goal enters the reasoning loop
- Diagnostics → Decision loop: bypasses · Diagnostics avoid autonomous planning
- Decision loop → Crypto layer: secures · Wraps remote exchanges in protected transport
- Crypto layer → AI backend: sends · Communicates with the remote intelligence backend
- AI backend → Decision loop: returns · Provides guidance or next-step data
- Decision loop → Command runner: issues · Turns decisions into shell actions
- Command runner → Platform bridge: adapts · Applies platform-specific command handling
- Platform bridge → Host shell: runs on · Executes directly on the host shell
- Command runner → Docker sandbox: optionally routes · Can isolate commands inside Docker
- Host shell → Live output: emits · Streams live command output
- Docker sandbox → Live output: emits · Streams sandboxed command output
- Live output → Decision loop: feedback · Output is analyzed for the next action