# cogensec/gideon architecture

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

- Interactive diagram: https://gitdiagram.com/cogensec/gideon
- Repository: https://github.com/cogensec/gideon

## Overview

1. **Repository shape**
   Gideon is a Bun/TypeScript monorepo centered on an autonomous cybersecurity agent. The runtime product is a terminal-first operator experience, while `docs/` is a separate Astro documentation site. The codebase is organized around one core loop: accept a security goal, plan work, invoke tools/services, validate findings, and emit a report or answer.

2. **Operator interface layer**
   The entry points in `src/cli.tsx` and `src/index.tsx`, plus `src/components/` and `src/hooks/`, form the interactive shell/UI layer. It handles prompt entry, command history, model selection, debug output, and progress indicators. This layer is mostly orchestration and presentation; it does not own the analysis logic.

3. **Agent core**
   `src/agent/` contains the ReAct-style execution engine: planning, phase management, approvals, prompts, scratchpad state, and a red-team mode switch. This is the central control loop that turns a user request into a sequence of actions, observations, and reflections. It is the main boundary between user intent and the rest of the system.

4. **Tool and data-source boundary**
   `src/tools/` and `src/utils/llm-*` provide the external I/O adapters. They connect to LLM providers and research sources such as OpenRouter, OpenAI, Anthropic, Google, Ollama, Exa, Tavily, NVD, VirusTotal, and AbuseIPDB. In architecture terms, this is the outbound integration layer for model inference, threat intel lookup, and search.

5. **Domain capabilities**
   The product’s primary security workflows live in `src/gideon/`, `src/scanner/`, `src/output/`, `src/graph/`, and the command handlers under `src/commands/`. These subsystems cover CVE research, IOC reputation checks, briefing/report generation, scanning, and graph-based correlation. Commands like `brief`, `cve`, `ioc`, `policy`, `scan`, and `redteam` are just thin entry points into these domain engines.

6. **Skills subsystem**
   `src/skills/` is a modular capability system. Each skill directory represents a specialized subdomain with its own commands and behavior, such as security research, post-exploitation, weaponization, voice, governance, threat detection, and OpenClaw Sentinel. The `registry.ts` file indicates skills are dynamically discoverable and act like pluggable sub-agents rather than a flat command list.

7. **Safety, governance, and audit**
   `src/governance/` and `src/openclaw/` implement the defensive control plane: policy enforcement, access control, agent monitoring, audit logging, prompt-injection defense, credential guarding, memory integrity checks, and hardening audits. These modules sit on the critical path for both normal and red-team operations, so they are not optional decoration; they enforce scope, record actions, and block unsafe behavior.

8. **Red-team execution path**
   `src/redteam/` contains the offensive simulation stack: attack definitions, campaign management, scoring, and report generation. This path is distinct from the defensive research path and is intended for authorized engagements. The readme’s sandboxing and engagement-scope rules imply this subsystem must be diagrammed as gated by governance and isolated execution boundaries.

9. **C2 and post-exploitation integration**
   `src/c2/` plus the Sliver adapter connect Gideon to command-and-control style session infrastructure. This is the bridge from planning and analysis into post-exploitation session awareness, host mapping, and controlled operator actions. It is an external-security boundary and should be shown separately from general threat-intel tooling.

10. **MCP extensibility**
    `src/mcp/` and `mcp-servers/` provide Model Context Protocol integration for external tools. The repository includes a Python MCP server container, which means tool expansion is meant to happen through a protocol boundary rather than only in-process code. In diagrams, MCP should be treated as a plugin surface that feeds additional tools into the agent loop.

11. **Configuration, state, and cross-cutting utilities**
    `src/utils/` contains the shared support systems: configuration loading, environment handling, caching, rate limiting, redaction, logger, chat history, and provider-specific helpers. `gideon.config.yaml` and `.env` determine runtime behavior, enabled providers, security integrations, and model routing. These utilities are the common substrate used by nearly every subsystem.

12. **Supporting infrastructure**
    `docker-compose.yml` and the `mcp-servers/Dockerfile` indicate containerized auxiliary services, especially for sandboxed or protocol-based integrations. The docs site under `docs/` is a separate application with its own build/runtime. The architecture therefore has three distinct deployment surfaces: the Bun CLI app, optional containerized support services, and the documentation site.

Main entry points: [`src/agent`](https://github.com/cogensec/gideon/tree/main/src/agent) (Agent loop), [`src/cli.tsx`](https://github.com/cogensec/gideon/blob/main/src/cli.tsx) (CLI shell), [`src/gideon`](https://github.com/cogensec/gideon/tree/main/src/gideon) (Domain engines), [`src/governance`](https://github.com/cogensec/gideon/tree/main/src/governance) (Governance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Bun app"]
  node_src_index["App entry<br/>runtime entry<br/>[index.tsx]"]
  node_src_cli["CLI shell<br/>terminal UI<br/>[cli.tsx]"]
  node_ui_components["UI widgets<br/>terminal components"]
  node_ui_hooks["UI hooks<br/>state hooks"]
  node_agent_core{{"Agent loop<br/>ReAct engine"}}
  node_agent_phases["Phases<br/>phase control<br/>[phases.ts]"]
  node_agent_approval["Approvals<br/>safety gate<br/>[approval.ts]"]
  node_agent_prompts["Prompts<br/>prompting<br/>[prompts.ts]"]
  node_agent_redteam_mode["Red-team mode<br/>mode switch<br/>[redteam-mode.ts]"]
  node_commands["Commands<br/>command handlers"]
  node_domain_caps["Domain engines<br/>security workflows"]
  node_scanner["Scanner<br/>pattern scan"]
  node_graph_engine["Graph engine<br/>correlation graph"]
  node_output_layer["Output<br/>reporting"]
  node_skills_registry["Skills registry<br/>pluggable skills<br/>[registry.ts]"]
  node_governance[("Governance<br/>policy control")]
  node_openclaw["OpenClaw<br/>defensive controls"]
  node_redteam["Red team<br/>offensive simulation"]
  node_c2["C2 bridge<br/>session integration"]
  node_tools_llm["LLM tools<br/>model adapters"]
  node_tools_security["Security tools<br/>intel connectors"]
  node_mcp["MCP surface<br/>plugin protocol"]
end

subgraph group_docs["Docs site"]
  node_docs_site["Docs app<br/>Astro site"]
end

subgraph group_support["Support services"]
  node_mcp_servers["MCP server<br/>container service"]
end

node_src_index -->|"boots"| node_src_cli
node_src_cli -->|"renders"| node_ui_components
node_src_cli -->|"binds state"| node_ui_hooks
node_src_cli -->|"invokes"| node_agent_core
node_agent_core -->|"organizes"| node_agent_phases
node_agent_core -->|"checks"| node_agent_approval
node_agent_core -->|"templates"| node_agent_prompts
node_agent_core -->|"switches"| node_agent_redteam_mode
node_commands -->|"dispatches"| node_domain_caps
node_domain_caps -->|"uses"| node_scanner
node_domain_caps -->|"correlates"| node_graph_engine
node_domain_caps -->|"formats"| node_output_layer
node_skills_registry -->|"extends"| node_agent_core
node_governance -->|"guards"| node_agent_core
node_governance -->|"gates"| node_redteam
node_openclaw -->|"reinforces"| node_governance
node_redteam -->|"reports"| node_output_layer
node_c2 -->|"feeds"| node_agent_core
node_tools_llm -->|"supplies models"| node_agent_core
node_tools_security -->|"supplies intel"| node_domain_caps
node_mcp -->|"adds tools"| node_skills_registry
node_mcp -->|"plugs into"| node_agent_core
node_docs_site -.->|"documents"| node_src_cli
node_mcp_servers -->|"hosts"| node_mcp

click node_src_index "https://github.com/cogensec/gideon/blob/main/src/index.tsx"
click node_src_cli "https://github.com/cogensec/gideon/blob/main/src/cli.tsx"
click node_ui_components "https://github.com/cogensec/gideon/tree/main/src/components"
click node_ui_hooks "https://github.com/cogensec/gideon/tree/main/src/hooks"
click node_agent_core "https://github.com/cogensec/gideon/tree/main/src/agent"
click node_agent_phases "https://github.com/cogensec/gideon/blob/main/src/agent/phases.ts"
click node_agent_approval "https://github.com/cogensec/gideon/blob/main/src/agent/approval.ts"
click node_agent_prompts "https://github.com/cogensec/gideon/blob/main/src/agent/prompts.ts"
click node_agent_redteam_mode "https://github.com/cogensec/gideon/blob/main/src/agent/redteam-mode.ts"
click node_commands "https://github.com/cogensec/gideon/tree/main/src/commands"
click node_domain_caps "https://github.com/cogensec/gideon/tree/main/src/gideon"
click node_scanner "https://github.com/cogensec/gideon/tree/main/src/scanner"
click node_graph_engine "https://github.com/cogensec/gideon/tree/main/src/graph"
click node_output_layer "https://github.com/cogensec/gideon/tree/main/src/output"
click node_skills_registry "https://github.com/cogensec/gideon/blob/main/src/skills/registry.ts"
click node_governance "https://github.com/cogensec/gideon/tree/main/src/governance"
click node_openclaw "https://github.com/cogensec/gideon/tree/main/src/openclaw"
click node_redteam "https://github.com/cogensec/gideon/tree/main/src/redteam"
click node_c2 "https://github.com/cogensec/gideon/tree/main/src/c2"
click node_tools_llm "https://github.com/cogensec/gideon/tree/main/src/utils"
click node_tools_security "https://github.com/cogensec/gideon/tree/main/src/tools"
click node_mcp "https://github.com/cogensec/gideon/tree/main/src/mcp"
click node_docs_site "https://github.com/cogensec/gideon/tree/main/docs"
click node_mcp_servers "https://github.com/cogensec/gideon/tree/main/mcp-servers"

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_src_index,node_src_cli,node_ui_components,node_ui_hooks,node_agent_core,node_agent_phases,node_agent_approval,node_agent_prompts,node_agent_redteam_mode,node_commands,node_domain_caps,node_scanner,node_graph_engine,node_output_layer,node_skills_registry,node_governance,node_openclaw,node_redteam,node_c2,node_tools_llm,node_tools_security,node_mcp toneBlue
class node_docs_site toneAmber
class node_mcp_servers toneMint
```

## Components

### Bun app

Main terminal-first Gideon application and its runtime subsystems.

- [App entry](https://github.com/cogensec/gideon/blob/main/src/index.tsx): runtime entry · Starts the Bun application and wires the terminal experience. · `src/index.tsx`
- [CLI shell](https://github.com/cogensec/gideon/blob/main/src/cli.tsx): terminal UI · Command-line entrypoint for user interaction and command dispatch. · `src/cli.tsx`
- [UI widgets](https://github.com/cogensec/gideon/tree/main/src/components): terminal components · Interactive presentation layer for prompts, history, status, and debug output. · `src/components`
- [UI hooks](https://github.com/cogensec/gideon/tree/main/src/hooks): state hooks · Shared input, history, model, and runner state for the operator shell. · `src/hooks`
- [Agent loop](https://github.com/cogensec/gideon/tree/main/src/agent): ReAct engine · Main planning and execution loop that turns goals into actions and observations. · `src/agent`
- [Phases](https://github.com/cogensec/gideon/blob/main/src/agent/phases.ts): phase control · Structures the agent lifecycle and execution stages. · `src/agent/phases.ts`
- [Approvals](https://github.com/cogensec/gideon/blob/main/src/agent/approval.ts): safety gate · Approval and permission checks before sensitive actions proceed. · `src/agent/approval.ts`
- [Prompts](https://github.com/cogensec/gideon/blob/main/src/agent/prompts.ts): prompting · System and task prompt templates for the agent loop. · `src/agent/prompts.ts`
- [Red-team mode](https://github.com/cogensec/gideon/blob/main/src/agent/redteam-mode.ts): mode switch · Specialized execution mode for offensive simulation workflows. · `src/agent/redteam-mode.ts`
- [Commands](https://github.com/cogensec/gideon/tree/main/src/commands): command handlers · Thin entrypoints for brief, CVE, IOC, policy, scan, redteam, and related actions. · `src/commands`
- [Domain engines](https://github.com/cogensec/gideon/tree/main/src/gideon): security workflows · Core research, scanning, reporting, and graph correlation capabilities. · `src/gideon`
- [Scanner](https://github.com/cogensec/gideon/tree/main/src/scanner): pattern scan · Detection and report pipeline for scanning-focused workflows. · `src/scanner`
- [Graph engine](https://github.com/cogensec/gideon/tree/main/src/graph): correlation graph · Builds graph-based relationships between findings and entities. · `src/graph`
- [Output](https://github.com/cogensec/gideon/tree/main/src/output): reporting · Formats answers and reports as JSON or Markdown. · `src/output`
- [Skills registry](https://github.com/cogensec/gideon/blob/main/src/skills/registry.ts): pluggable skills · Discovers and exposes modular skills as specialized sub-agents. · `src/skills/registry.ts`
- [Governance](https://github.com/cogensec/gideon/tree/main/src/governance): policy control · Policy enforcement, access control, auditing, and monitoring. · `src/governance`
- [OpenClaw](https://github.com/cogensec/gideon/tree/main/src/openclaw): defensive controls · Prompt-injection defense, credential guarding, integrity checks, and hardening audits. · `src/openclaw`
- [Red team](https://github.com/cogensec/gideon/tree/main/src/redteam): offensive simulation · Campaigns, attacks, scoring, and red-team report generation. · `src/redteam`
- [C2 bridge](https://github.com/cogensec/gideon/tree/main/src/c2): session integration · Connects planning and analysis to command-and-control style session infrastructure. · `src/c2`
- [LLM tools](https://github.com/cogensec/gideon/tree/main/src/utils): model adapters · Outbound adapters for model providers and tool-backed inference. · `src/utils`
- [Security tools](https://github.com/cogensec/gideon/tree/main/src/tools): intel connectors · Adapters for CVE, IOC, search, and external threat-intelligence sources. · `src/tools`
- [MCP surface](https://github.com/cogensec/gideon/tree/main/src/mcp): plugin protocol · Model Context Protocol integration for external tools and servers. · `src/mcp`

### Docs site

Separate Astro documentation application.

- [Docs app](https://github.com/cogensec/gideon/tree/main/docs): Astro site · Separate documentation application and content site. · `docs`

### Support services

Containerized or protocol-based auxiliary infrastructure.

- [MCP server](https://github.com/cogensec/gideon/tree/main/mcp-servers): container service · Python-based containerized MCP server support. · `mcp-servers`

## Connections

- App entry → CLI shell: boots · The runtime entrypoint initializes the CLI shell.
- CLI shell → UI widgets: renders · CLI uses shared terminal UI components.
- CLI shell → UI hooks: binds state · Input, history, and model selection flow through hooks.
- CLI shell → Agent loop: invokes · User goals are handed to the agent execution loop.
- Agent loop → Phases: organizes · The loop is structured into phases.
- Agent loop → Approvals: checks · Sensitive steps pass through approval gates.
- Agent loop → Prompts: templates · Prompt construction is centralized.
- Agent loop → Red-team mode: switches · Red-team workflows use a distinct execution mode.
- Commands → Domain engines: dispatches · Commands mostly forward into domain engines.
- Domain engines → Scanner: uses · Security workflows can invoke scanning capabilities.
- Domain engines → Graph engine: correlates · Findings can be organized as graphs.
- Domain engines → Output: formats · Domain results are emitted as reports or structured answers.
- Skills registry → Agent loop: extends · Skills act as pluggable capabilities for the main loop.
- Governance → Agent loop: guards · Policy and audit controls sit on the critical path.
- Governance → Red team: gates · Offensive simulation runs under governance control.
- OpenClaw → Governance: reinforces · Defensive controls complement policy enforcement and audit.
- Red team → Output: reports · Campaigns produce scored reports and summaries.
- C2 bridge → Agent loop: feeds · Session-aware post-exploitation context can inform the agent.
- LLM tools → Agent loop: supplies models · Model inference adapters are consumed by the agent loop.
- Security tools → Domain engines: supplies intel · Threat-intel and search connectors back domain workflows.
- MCP surface → Skills registry: adds tools · Protocol-based tools surface through skills and the agent loop.
- MCP surface → Agent loop: plugs into · MCP expands the agent's tool boundary.
- Docs app → CLI shell: documents · Documentation describes the runtime product and workflows.
- MCP server → MCP surface: hosts · Containerized server support sits behind the MCP surface.