# song-g-s/engima architecture

> Architecture diagram of the GitHub repository song-g-s/engima, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/song-g-s/engima
- Repository: https://github.com/song-g-s/engima

## Overview

SWE-agent turns an issue or challenge into an agent-run repository change: the runner prepares an environment, the agent interacts with a language model and executes actions in that environment, then the run records a trajectory and submission. The repository also includes a web interface for launching and observing runs, a trajectory inspector, and EnIGMA-oriented challenge tools. The main workflow is supported by the excerpts and source index; some web and challenge-tool wiring is not shown, so those connections are omitted or marked unverified.

Main entry points: [`sweagent/agent/agents.py`](https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/agents.py) (Agent loop), [`run.py`](https://github.com/song-g-s/engima/blob/xsj/run.py) (Run coordinator), [`sweagent/environment/swe_env.py`](https://github.com/song-g-s/engima/blob/xsj/sweagent/environment/swe_env.py) (Repository environment), [`sweagent/api/hooks.py`](https://github.com/song-g-s/engima/blob/xsj/sweagent/api/hooks.py) (Live update hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_runner["Run coordinator<br/>[run.py]"]
  node_trajectory["Run trajectories<br/>[run.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_agent["Agent runtime"]
  node_agent_core["Agent loop<br/>[agents.py]"]
  node_commands["Agent commands<br/>[commands.py]"]
  node_parsing["Response parsing<br/>[parsing.py]"]
  node_models["Language models<br/>[models.py]"]
  node_history["History processing"]
  node_summarizer["Output summarizer<br/>[summarizer.py]"]
  node_interactive["Interactive tools"]
end

subgraph group_environment["Execution environment"]
  node_environment["Repository environment<br/>[swe_env.py]"]
  node_container_utils["Container utilities<br/>[utils.py]"]
end

subgraph group_web["Web interface"]
  node_web_api["Web run API<br/>[server.py]"]
  node_web_hooks["Live update hooks<br/>[hooks.py]"]
  node_web_client["Run interface<br/>[Run.js]"]
  node_inspector["Trajectory inspector<br/>[server.py]"]
end

subgraph group_enigma["EnIGMA tools"]
  node_ctf_runner["CTF batch runner<br/>[solve_all_ctf.py]"]
  node_decompile["Decompile commands<br/>[decompile.py]"]
  node_disassemble["Disassembly commands<br/>[disassemble.py]"]
  node_filemap["Challenge file map<br/>[filemap.py]"]
  node_ghidra_decompile["Ghidra decompiler"]
  node_ghidra_disassemble["Ghidra disassembler"]
end

node_user(("Engineer"))

node_user -->|"starts run"| node_runner
node_runner -->|"creates environment"| node_environment
node_runner -->|"runs agent"| node_agent_core
node_runner -->|"saves results"| node_trajectory
node_agent_core -->|"queries model"| node_models
node_agent_core -->|"parses responses"| node_parsing
node_agent_core -->|"uses commands"| node_commands
node_agent_core -->|"processes history"| node_history
node_agent_core -->|"uses summarizer"| node_summarizer
node_agent_core -->|"executes actions"| node_environment
node_agent_core -->|"uses tools"| node_interactive
node_environment -->|"uses utilities"| node_container_utils
node_runner -->|"loads configuration"| node_config
node_user -->|"uses interface"| node_web_client
node_web_api -->|"starts run"| node_runner
node_web_api -->|"registers hooks"| node_web_hooks
node_web_hooks -->|"observes agent"| node_agent_core
node_web_hooks -->|"observes environment"| node_environment
node_web_client -.-> node_web_api
node_inspector -->|"serves trajectories"| node_trajectory
node_ctf_runner -->|"invokes runner"| node_runner
node_decompile -.-> node_ghidra_decompile
node_disassemble -.-> node_ghidra_disassemble
node_agent_core -.-> node_decompile
node_agent_core -.-> node_disassemble
node_agent_core -.-> node_filemap

click node_runner "https://github.com/song-g-s/engima/blob/xsj/run.py"
click node_trajectory "https://github.com/song-g-s/engima/blob/xsj/run.py"
click node_agent_core "https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/agents.py"
click node_commands "https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/commands.py"
click node_parsing "https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/parsing.py"
click node_models "https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/models.py"
click node_history "https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/history_processors.py"
click node_summarizer "https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/summarizer.py"
click node_interactive "https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/interactive_commands.py"
click node_environment "https://github.com/song-g-s/engima/blob/xsj/sweagent/environment/swe_env.py"
click node_container_utils "https://github.com/song-g-s/engima/blob/xsj/sweagent/environment/utils.py"
click node_config "https://github.com/song-g-s/engima/blob/xsj/sweagent/utils/config.py"
click node_web_api "https://github.com/song-g-s/engima/blob/xsj/sweagent/api/server.py"
click node_web_hooks "https://github.com/song-g-s/engima/blob/xsj/sweagent/api/hooks.py"
click node_web_client "https://github.com/song-g-s/engima/blob/xsj/sweagent/frontend/src/Run.js"
click node_inspector "https://github.com/song-g-s/engima/blob/xsj/inspector/server.py"
click node_ctf_runner "https://github.com/song-g-s/engima/blob/xsj/solve_all_ctf.py"
click node_decompile "https://github.com/song-g-s/engima/blob/xsj/config/commands/decompile.py"
click node_disassemble "https://github.com/song-g-s/engima/blob/xsj/config/commands/disassemble.py"
click node_filemap "https://github.com/song-g-s/engima/blob/xsj/config/commands/filemap.py"
click node_ghidra_decompile "https://github.com/song-g-s/engima/blob/xsj/docker/ghidra_scripts/DecompileToJson.java"
click node_ghidra_disassemble "https://github.com/song-g-s/engima/blob/xsj/docker/ghidra_scripts/DisassembleToJson.java"

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_runner,node_trajectory,node_config toneBlue
class node_agent_core,node_commands,node_parsing,node_models,node_history,node_summarizer,node_interactive toneAmber
class node_environment,node_container_utils toneMint
class node_web_api,node_web_hooks,node_web_client,node_inspector toneRose
class node_ctf_runner,node_decompile,node_disassemble,node_filemap,node_ghidra_decompile,node_ghidra_disassemble,node_user toneIndigo
```

## Components

### Run orchestration

- [Run coordinator](https://github.com/song-g-s/engima/blob/xsj/run.py): `run.py`
- [Run trajectories](https://github.com/song-g-s/engima/blob/xsj/run.py): `run.py`
- [Runtime configuration](https://github.com/song-g-s/engima/blob/xsj/sweagent/utils/config.py): `sweagent/utils/config.py`

### Agent runtime

- [Agent loop](https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/agents.py): `sweagent/agent/agents.py`
- [Agent commands](https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/commands.py): `sweagent/agent/commands.py`
- [Response parsing](https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/parsing.py): `sweagent/agent/parsing.py`
- [Language models](https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/models.py): `sweagent/agent/models.py`
- [History processing](https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/history_processors.py): `sweagent/agent/history_processors.py`
- [Output summarizer](https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/summarizer.py): `sweagent/agent/summarizer.py`
- [Interactive tools](https://github.com/song-g-s/engima/blob/xsj/sweagent/agent/interactive_commands.py): `sweagent/agent/interactive_commands.py`

### Execution environment

- [Repository environment](https://github.com/song-g-s/engima/blob/xsj/sweagent/environment/swe_env.py): `sweagent/environment/swe_env.py`
- [Container utilities](https://github.com/song-g-s/engima/blob/xsj/sweagent/environment/utils.py): `sweagent/environment/utils.py`

### Web interface

- [Web run API](https://github.com/song-g-s/engima/blob/xsj/sweagent/api/server.py): `sweagent/api/server.py`
- [Live update hooks](https://github.com/song-g-s/engima/blob/xsj/sweagent/api/hooks.py): `sweagent/api/hooks.py`
- [Run interface](https://github.com/song-g-s/engima/blob/xsj/sweagent/frontend/src/Run.js): `sweagent/frontend/src/Run.js`
- [Trajectory inspector](https://github.com/song-g-s/engima/blob/xsj/inspector/server.py): `inspector/server.py`

### EnIGMA tools

- [CTF batch runner](https://github.com/song-g-s/engima/blob/xsj/solve_all_ctf.py): `solve_all_ctf.py`
- [Decompile commands](https://github.com/song-g-s/engima/blob/xsj/config/commands/decompile.py): `config/commands/decompile.py`
- [Disassembly commands](https://github.com/song-g-s/engima/blob/xsj/config/commands/disassemble.py): `config/commands/disassemble.py`
- [Challenge file map](https://github.com/song-g-s/engima/blob/xsj/config/commands/filemap.py): `config/commands/filemap.py`
- [Ghidra decompiler](https://github.com/song-g-s/engima/blob/xsj/docker/ghidra_scripts/DecompileToJson.java): `docker/ghidra_scripts/DecompileToJson.java`
- [Ghidra disassembler](https://github.com/song-g-s/engima/blob/xsj/docker/ghidra_scripts/DisassembleToJson.java): `docker/ghidra_scripts/DisassembleToJson.java`

### Other components

- **Engineer**

## Connections

- Engineer → Run coordinator: starts run (evidence: `README.md`)
- Run coordinator → Repository environment: creates environment (evidence: `run.py`)
- Run coordinator → Agent loop: runs agent (evidence: `run.py`)
- Run coordinator → Run trajectories: saves results (evidence: `run.py`)
- Agent loop → Language models: queries model (evidence: `sweagent/agent/agents.py`)
- Agent loop → Response parsing: parses responses (evidence: `sweagent/agent/agents.py`)
- Agent loop → Agent commands: uses commands (evidence: `sweagent/agent/agents.py`)
- Agent loop → History processing: processes history (evidence: `sweagent/agent/agents.py`)
- Agent loop → Output summarizer: uses summarizer (evidence: `sweagent/agent/agents.py`)
- Agent loop → Repository environment: executes actions (evidence: `sweagent/agent/agents.py`)
- Agent loop → Interactive tools: uses tools (evidence: `sweagent/agent/agents.py`)
- Repository environment → Container utilities: uses utilities (evidence: `sweagent/environment/swe_env.py`)
- Run coordinator → Runtime configuration: loads configuration (evidence: `run.py`)
- Engineer → Run interface: uses interface (evidence: `README.md`)
- Web run API → Run coordinator: starts run (evidence: `sweagent/api/server.py`)
- Web run API → Live update hooks: registers hooks (evidence: `sweagent/api/server.py`)
- Live update hooks → Agent loop: observes agent (evidence: `sweagent/api/hooks.py`)
- Live update hooks → Repository environment: observes environment (evidence: `sweagent/api/hooks.py`)
- Run interface → Web run API
- Trajectory inspector → Run trajectories: serves trajectories (evidence: `inspector/server.py`)
- CTF batch runner → Run coordinator: invokes runner (evidence: `solve_all_ctf.py`)
- Decompile commands → Ghidra decompiler
- Disassembly commands → Ghidra disassembler
- Agent loop → Decompile commands
- Agent loop → Disassembly commands
- Agent loop → Challenge file map
