# algorithmicmind/codeshield architecture

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

- Interactive diagram: https://gitdiagram.com/algorithmicmind/codeshield
- Repository: https://github.com/algorithmicmind/codeshield

## Overview

CodeShield is a Python execution runtime for code generated by people or AI agents. Its main workflow accepts code, validates it through an AST security gate, runs it in an isolated temporary environment, detects runtime or suspicious-output failures, and attempts diagnosis and repair before returning results. The CLI and agent-tool wrapper are separate entry points into the same engine. The README documents the main flow; sampled source confirms key orchestration and sandbox behavior, while some internal repair details are not fully excerpted.

Main entry points: [`src/codeshield/loop.py`](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/loop.py) (Self-healing engine), [`src/codeshield/cli.py`](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/cli.py) (Command-line interface), [`src/codeshield/tools.py`](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/tools.py) (Agent execution tool), [`src/codeshield/schemas.py`](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/schemas.py) (Execution result and diagnosis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["Command-line interface<br/>[cli.py]"]
  node_tool["Agent execution tool<br/>[tools.py]"]
end

subgraph group_engine["Execution and recovery"]
  node_engine["Self-healing engine<br/>[loop.py]"]
  node_ast_gate["AST security gate<br/>[analyzer.py]"]
  node_sandbox["Sandbox manager<br/>[environment.py]"]
  node_runner["Subprocess runner<br/>[runner.py]"]
  node_classifier["Traceback classifier<br/>[classifier.py]"]
  node_local_repair["Local repair heuristics<br/>[loop.py]"]
  node_llm_repair["LLM patch generation<br/>[loop.py]"]
end

subgraph group_contracts["Runtime contracts"]
  node_request["Execution request<br/>[schemas.py]"]
  node_result["Execution result and diagnosis<br/>[schemas.py]"]
end

node_cli_user(("CLI user"))
node_agent(("Agent or caller"))
node_llm_provider{{"Configured LLM provider"}}

node_cli_user -->|"submits code"| node_cli
node_cli -->|"runs code"| node_engine
node_agent -->|"provides code"| node_tool
node_tool -->|"invokes"| node_engine
node_cli -.->|"forms request"| node_request
node_engine -->|"accepts"| node_request
node_engine -->|"validates code"| node_ast_gate
node_engine -->|"creates and cleans"| node_sandbox
node_engine -->|"executes request"| node_runner
node_runner -->|"uses interpreter"| node_sandbox
node_engine -->|"classifies failures"| node_classifier
node_engine -->|"tries local repair"| node_local_repair
node_engine -->|"requests patch"| node_llm_repair
node_llm_repair -.->|"requests patch"| node_llm_provider
node_engine -->|"returns outcome"| node_result
node_tool -->|"formats outcome"| node_result
node_cli -->|"prints outcome"| node_result

click node_cli "https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/cli.py"
click node_tool "https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/tools.py"
click node_engine "https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/loop.py"
click node_ast_gate "https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/analyzer.py"
click node_sandbox "https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/environment.py"
click node_runner "https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/runner.py"
click node_classifier "https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/classifier.py"
click node_local_repair "https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/loop.py"
click node_llm_repair "https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/loop.py"
click node_request "https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/schemas.py"
click node_result "https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/schemas.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_cli,node_tool,node_cli_user toneBlue
class node_engine,node_ast_gate,node_sandbox,node_runner,node_classifier,node_local_repair,node_llm_repair toneAmber
class node_request,node_result toneMint
class node_agent,node_llm_provider toneIndigo
```

## Components

### Entry points

- [Command-line interface](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/cli.py): `src/codeshield/cli.py`
- [Agent execution tool](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/tools.py): `src/codeshield/tools.py`

### Execution and recovery

- [Self-healing engine](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/loop.py): `src/codeshield/loop.py`
- [AST security gate](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/analyzer.py): `src/codeshield/analyzer.py`
- [Sandbox manager](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/environment.py): `src/codeshield/environment.py`
- [Subprocess runner](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/runner.py): `src/codeshield/runner.py`
- [Traceback classifier](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/classifier.py): `src/codeshield/classifier.py`
- [Local repair heuristics](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/loop.py): `src/codeshield/loop.py`
- [LLM patch generation](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/loop.py): `src/codeshield/loop.py`

### Runtime contracts

- [Execution request](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/schemas.py): `src/codeshield/schemas.py`
- [Execution result and diagnosis](https://github.com/algorithmicmind/codeshield/blob/main/src/codeshield/schemas.py): `src/codeshield/schemas.py`

### Other components

- **CLI user**
- **Agent or caller**
- **Configured LLM provider**

## Connections

- CLI user → Command-line interface: submits code (evidence: `README.md`)
- Command-line interface → Self-healing engine: runs code (evidence: `src/codeshield/cli.py`)
- Agent or caller → Agent execution tool: provides code (evidence: `README.md`)
- Agent execution tool → Self-healing engine: invokes (evidence: `src/codeshield/tools.py`)
- Command-line interface → Execution request: forms request
- Self-healing engine → Execution request: accepts (evidence: `README.md`)
- Self-healing engine → AST security gate: validates code (evidence: `README.md`)
- Self-healing engine → Sandbox manager: creates and cleans (evidence: `src/codeshield/loop.py`)
- Self-healing engine → Subprocess runner: executes request (evidence: `src/codeshield/loop.py`)
- Subprocess runner → Sandbox manager: uses interpreter (evidence: `src/codeshield/runner.py`)
- Self-healing engine → Traceback classifier: classifies failures (evidence: `README.md`)
- Self-healing engine → Local repair heuristics: tries local repair (evidence: `README.md`)
- Self-healing engine → LLM patch generation: requests patch (evidence: `README.md`)
- LLM patch generation → Configured LLM provider: requests patch (evidence: `README.md`)
- Self-healing engine → Execution result and diagnosis: returns outcome (evidence: `README.md`)
- Agent execution tool → Execution result and diagnosis: formats outcome (evidence: `src/codeshield/tools.py`)
- Command-line interface → Execution result and diagnosis: prints outcome (evidence: `src/codeshield/cli.py`)
