# bp974/safe-agent architecture

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

- Interactive diagram: https://gitdiagram.com/bp974/safe-agent
- Repository: https://github.com/bp974/safe-agent

## Overview

Safe Agent isolates coding agents in Docker against safe project copies, then uses reviewed Git commits to transfer changes to and from real repositories. The README documents the workflow and integrations; the only sampled implementation is the project-config validator, so command-to-command internals are not inferred.

Main entry points: [`bin/agent-start`](https://github.com/bp974/safe-agent/blob/main/bin/agent-start) (Start agent), [`bin/agent-pull`](https://github.com/bp974/safe-agent/blob/main/bin/agent-pull) (Pull changes), [`bin/agent-push`](https://github.com/bp974/safe-agent/blob/main/bin/agent-push) (Push changes), [`container/Dockerfile`](https://github.com/bp974/safe-agent/blob/main/container/Dockerfile) (Docker container)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Project workflow"]
  node_real[("Real repositories")]
  node_safe[("Safe project copies")]
  node_pull["Pull changes"]
  node_push["Push changes"]
end

subgraph group_isolation["Agent isolation"]
  node_start["Start agent"]
  node_docker["Docker container"]
  node_agents["Coding agents"]
  node_agentstate[("Persistent agent state")]
end

subgraph group_configuration["Runtime configuration"]
  node_projectconfig["Project config"]
  node_configreader["Config validator"]
  node_localsettings["Local settings<br/>[.env.example]"]
  node_mounts["Extra host mounts"]
end

subgraph group_integrations["Optional integrations"]
  node_fusion["Fusion 360 integration"]
end

node_developer(("Developer"))

node_developer -->|"runs"| node_pull
node_pull -->|"reads commits"| node_real
node_pull -->|"updates commits"| node_safe
node_developer -->|"runs"| node_start
node_start -->|"mounts project"| node_safe
node_start -->|"starts"| node_docker
node_docker -->|"runs selected"| node_agents
node_docker -->|"persists state"| node_agentstate
node_agents -->|"edits and commits"| node_safe
node_developer -->|"runs and confirms"| node_push
node_push -->|"fetches commits"| node_safe
node_push -->|"fast-forwards"| node_real
node_start -->|"reads settings"| node_localsettings
node_start -.->|"loads project config"| node_projectconfig
node_projectconfig -.->|"validated by"| node_configreader
node_start -.->|"configures mounts"| node_mounts
node_agents -.->|"optional integration"| node_fusion

click node_pull "https://github.com/bp974/safe-agent/blob/main/bin/agent-pull"
click node_push "https://github.com/bp974/safe-agent/blob/main/bin/agent-push"
click node_start "https://github.com/bp974/safe-agent/blob/main/bin/agent-start"
click node_docker "https://github.com/bp974/safe-agent/blob/main/container/Dockerfile"
click node_agents "https://github.com/bp974/safe-agent/tree/main/container"
click node_agentstate "https://github.com/bp974/safe-agent/tree/main/container"
click node_configreader "https://github.com/bp974/safe-agent/blob/main/bin/read-safe-agent-config.py"
click node_localsettings "https://github.com/bp974/safe-agent/blob/main/.env.example"
click node_mounts "https://github.com/bp974/safe-agent/blob/main/bin/read-safe-agent-config.py"
click node_fusion "https://github.com/bp974/safe-agent/blob/main/docs/integrations/fusion-360-wsl-mcp.md"

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_real,node_safe,node_pull,node_push toneBlue
class node_start,node_docker,node_agents,node_agentstate toneAmber
class node_projectconfig,node_configreader,node_localsettings,node_mounts toneMint
class node_fusion toneRose
class node_developer toneIndigo
```

## Components

### Project workflow

- **Real repositories**
- **Safe project copies**
- [Pull changes](https://github.com/bp974/safe-agent/blob/main/bin/agent-pull): `bin/agent-pull`
- [Push changes](https://github.com/bp974/safe-agent/blob/main/bin/agent-push): `bin/agent-push`

### Agent isolation

- [Start agent](https://github.com/bp974/safe-agent/blob/main/bin/agent-start): `bin/agent-start`
- [Docker container](https://github.com/bp974/safe-agent/blob/main/container/Dockerfile): `container/Dockerfile`
- [Coding agents](https://github.com/bp974/safe-agent/tree/main/container): `container`
- [Persistent agent state](https://github.com/bp974/safe-agent/tree/main/container): `container`

### Runtime configuration

- **Project config**
- [Config validator](https://github.com/bp974/safe-agent/blob/main/bin/read-safe-agent-config.py): `bin/read-safe-agent-config.py`
- [Local settings](https://github.com/bp974/safe-agent/blob/main/.env.example): `.env.example`
- [Extra host mounts](https://github.com/bp974/safe-agent/blob/main/bin/read-safe-agent-config.py): `bin/read-safe-agent-config.py`

### Optional integrations

- [Fusion 360 integration](https://github.com/bp974/safe-agent/blob/main/docs/integrations/fusion-360-wsl-mcp.md): `docs/integrations/fusion-360-wsl-mcp.md`

### Other components

- **Developer**

## Connections

- Developer → Pull changes: runs
- Pull changes → Real repositories: reads commits
- Pull changes → Safe project copies: updates commits
- Developer → Start agent: runs
- Start agent → Safe project copies: mounts project
- Start agent → Docker container: starts
- Docker container → Coding agents: runs selected
- Docker container → Persistent agent state: persists state
- Coding agents → Safe project copies: edits and commits
- Developer → Push changes: runs and confirms
- Push changes → Safe project copies: fetches commits
- Push changes → Real repositories: fast-forwards
- Start agent → Local settings: reads settings
- Start agent → Project config: loads project config
- Project config → Config validator: validated by
- Start agent → Extra host mounts: configures mounts
- Coding agents → Fusion 360 integration: optional integration