# deviousdevv303/forgeclaw architecture

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

- Interactive diagram: https://gitdiagram.com/deviousdevv303/forgeclaw
- Repository: https://github.com/deviousdevv303/forgeclaw

## Overview

ForgeClaw is an operator-controlled AI development and automation console. The main workflow starts in the browser workspace: a user submits a request, the app routes it to a configured provider, and any requested side effects run through ForgeTools and Guardian before results and failures are surfaced. The product also supports GitHub and Pages operations, live research, image input, self-sculpt pull requests, browser automation, and NEXUS learning. The README documents these capabilities; sampled source confirms key App, router, and orchestration links, while some subsystem internals were not sampled.

Main entry points: [`src/lib/forgeTools.ts`](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/forgeTools.ts) (ForgeTools), [`src/App.tsx`](https://github.com/deviousdevv303/forgeclaw/blob/main/src/App.tsx) (Browser workspace), [`src/hooks/useOrchestrator.ts`](https://github.com/deviousdevv303/forgeclaw/blob/main/src/hooks/useOrchestrator.ts) (Task orchestration), [`src/lib/ai/providerRouter.ts`](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/ai/providerRouter.ts) (Provider router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Operator workspace"]
  node_app["Browser workspace<br/>[App.tsx]"]
  node_ui["Workspace panels<br/>[AgentsPanel.tsx]"]
end

subgraph group_runtime["Agent runtime"]
  node_orchestrator["Task orchestration<br/>[useOrchestrator.ts]"]
  node_router["Provider router<br/>[providerRouter.ts]"]
  node_providers["Provider adapters"]
  node_image["Image input<br/>[imageInput.ts]"]
end

subgraph group_integrations["Tools and integrations"]
  node_forge_tools["ForgeTools<br/>[forgeTools.ts]"]
  node_github["GitHub operations<br/>[github.ts]"]
  node_shell["Remote shell<br/>[shellCommand.ts]"]
  node_site["Pages publishing<br/>[siteBuild.ts]"]
  node_research["Web research<br/>[deepResearch.ts]"]
  node_browser["Browser automation<br/>[browserAgent.ts]"]
  node_sculpt["Self-sculpt workflow<br/>[sculptCommand.ts]"]
end

subgraph group_governance["Safety and observability"]
  node_autonomy["Autonomy policy<br/>[autonomyEngine.ts]"]
  node_integrity["Integrity validation"]
  node_guardian["Guardian gate<br/>[guardianGate.ts]"]
  node_failure["Failure dashboard"]
  node_storage[("Browser storage<br/>[storage.ts]")]
end

subgraph group_learning["NEXUS learning"]
  node_learning_events["Learning events<br/>[learningEvents.ts]"]
  node_corpus[("Evidence corpus<br/>[corpus.ts]")]
  node_nexus["NEXUS convergence"]
end

node_operator(("Operator"))
node_provider_service{{"Configured AI services"}}
node_github_actions{{"GitHub Actions runners"}}
node_live_web{{"Live web"}}

node_operator -->|"submits request"| node_app
node_app -->|"routes turn"| node_router
node_router -->|"dispatches provider"| node_providers
node_providers -->|"requests inference"| node_provider_service
node_router -->|"processes image input"| node_image
node_app -->|"executes tool"| node_forge_tools
node_app -->|"coordinates agents"| node_orchestrator
node_orchestrator -->|"evaluates admission"| node_autonomy
node_orchestrator -->|"validates output"| node_integrity
node_forge_tools -->|"checks side effects"| node_guardian
node_forge_tools -->|"performs repository work"| node_github
node_forge_tools -->|"dispatches command"| node_shell
node_forge_tools -->|"publishes site"| node_site
node_forge_tools -->|"runs research"| node_research
node_forge_tools -->|"starts automation"| node_browser
node_forge_tools -->|"opens review PR"| node_sculpt
node_github -->|"dispatches workflows"| node_github_actions
node_research -->|"searches and fetches"| node_live_web
node_browser -->|"runs automation"| node_github_actions
node_app -->|"surfaces failures"| node_failure
node_orchestrator -->|"emits failure events"| node_failure
node_app -->|"renders workspace panels"| node_ui
node_learning_events -->|"records outcomes"| node_corpus
node_nexus -->|"converges evidence"| node_corpus
node_app -->|"persists workspace state"| node_storage
node_autonomy -.->|"persists decision ledger"| node_storage

click node_app "https://github.com/deviousdevv303/forgeclaw/blob/main/src/App.tsx"
click node_ui "https://github.com/deviousdevv303/forgeclaw/blob/main/src/components/AgentsPanel.tsx"
click node_orchestrator "https://github.com/deviousdevv303/forgeclaw/blob/main/src/hooks/useOrchestrator.ts"
click node_autonomy "https://github.com/deviousdevv303/forgeclaw/blob/main/src/core/autonomyEngine.ts"
click node_integrity "https://github.com/deviousdevv303/forgeclaw/blob/main/src/hooks/useIntegrityGate.ts"
click node_router "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/ai/providerRouter.ts"
click node_providers "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/ai/providers/anthropicProvider.ts"
click node_forge_tools "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/forgeTools.ts"
click node_guardian "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/guardianGate.ts"
click node_github "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/github.ts"
click node_shell "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/shellCommand.ts"
click node_site "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/siteBuild.ts"
click node_research "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/deepResearch.ts"
click node_browser "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/browserAgent.ts"
click node_sculpt "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/sculptCommand.ts"
click node_image "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/imageInput.ts"
click node_failure "https://github.com/deviousdevv303/forgeclaw/blob/main/src/components/FailureDashboard.tsx"
click node_learning_events "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/learningEvents.ts"
click node_corpus "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/corpus.ts"
click node_nexus "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/nexusConvergence.ts"
click node_storage "https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/storage.ts"

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_app,node_ui toneBlue
class node_orchestrator,node_router,node_providers,node_image toneAmber
class node_forge_tools,node_github,node_shell,node_site,node_research,node_browser,node_sculpt toneMint
class node_autonomy,node_integrity,node_guardian,node_failure,node_storage toneRose
class node_learning_events,node_corpus,node_nexus,node_operator,node_provider_service,node_github_actions,node_live_web toneIndigo
```

## Components

### Operator workspace

- [Browser workspace](https://github.com/deviousdevv303/forgeclaw/blob/main/src/App.tsx): `src/App.tsx`
- [Workspace panels](https://github.com/deviousdevv303/forgeclaw/blob/main/src/components/AgentsPanel.tsx): `src/components/AgentsPanel.tsx`

### Agent runtime

- [Task orchestration](https://github.com/deviousdevv303/forgeclaw/blob/main/src/hooks/useOrchestrator.ts): `src/hooks/useOrchestrator.ts`
- [Provider router](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/ai/providerRouter.ts): `src/lib/ai/providerRouter.ts`
- [Provider adapters](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/ai/providers/anthropicProvider.ts): `src/lib/ai/providers/anthropicProvider.ts`
- [Image input](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/imageInput.ts): `src/lib/imageInput.ts`

### Tools and integrations

- [ForgeTools](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/forgeTools.ts): `src/lib/forgeTools.ts`
- [GitHub operations](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/github.ts): `src/lib/github.ts`
- [Remote shell](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/shellCommand.ts): `src/lib/shellCommand.ts`
- [Pages publishing](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/siteBuild.ts): `src/lib/siteBuild.ts`
- [Web research](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/deepResearch.ts): `src/lib/deepResearch.ts`
- [Browser automation](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/browserAgent.ts): `src/lib/browserAgent.ts`
- [Self-sculpt workflow](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/sculptCommand.ts): `src/lib/sculptCommand.ts`

### Safety and observability

- [Autonomy policy](https://github.com/deviousdevv303/forgeclaw/blob/main/src/core/autonomyEngine.ts): `src/core/autonomyEngine.ts`
- [Integrity validation](https://github.com/deviousdevv303/forgeclaw/blob/main/src/hooks/useIntegrityGate.ts): `src/hooks/useIntegrityGate.ts`
- [Guardian gate](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/guardianGate.ts): `src/lib/guardianGate.ts`
- [Failure dashboard](https://github.com/deviousdevv303/forgeclaw/blob/main/src/components/FailureDashboard.tsx): `src/components/FailureDashboard.tsx`
- [Browser storage](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/storage.ts): `src/lib/storage.ts`

### NEXUS learning

- [Learning events](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/learningEvents.ts): `src/lib/learningEvents.ts`
- [Evidence corpus](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/corpus.ts): `src/lib/corpus.ts`
- [NEXUS convergence](https://github.com/deviousdevv303/forgeclaw/blob/main/src/lib/nexusConvergence.ts): `src/lib/nexusConvergence.ts`

### Other components

- **Operator**
- **Configured AI services**
- **GitHub Actions runners**
- **Live web**

## Connections

- Operator → Browser workspace: submits request
- Browser workspace → Provider router: routes turn (evidence: `src/App.tsx`)
- Provider router → Provider adapters: dispatches provider (evidence: `src/lib/ai/providerRouter.ts`)
- Provider adapters → Configured AI services: requests inference
- Provider router → Image input: processes image input (evidence: `src/lib/ai/providerRouter.ts`)
- Browser workspace → ForgeTools: executes tool (evidence: `src/App.tsx`)
- Browser workspace → Task orchestration: coordinates agents (evidence: `src/App.tsx`)
- Task orchestration → Autonomy policy: evaluates admission (evidence: `src/hooks/useOrchestrator.ts`)
- Task orchestration → Integrity validation: validates output (evidence: `src/hooks/useOrchestrator.ts`)
- ForgeTools → Guardian gate: checks side effects
- ForgeTools → GitHub operations: performs repository work
- ForgeTools → Remote shell: dispatches command
- ForgeTools → Pages publishing: publishes site
- ForgeTools → Web research: runs research
- ForgeTools → Browser automation: starts automation
- ForgeTools → Self-sculpt workflow: opens review PR
- GitHub operations → GitHub Actions runners: dispatches workflows
- Web research → Live web: searches and fetches
- Browser automation → GitHub Actions runners: runs automation
- Browser workspace → Failure dashboard: surfaces failures (evidence: `src/App.tsx`)
- Task orchestration → Failure dashboard: emits failure events (evidence: `src/hooks/useOrchestrator.ts`)
- Browser workspace → Workspace panels: renders workspace panels (evidence: `src/App.tsx`)
- Learning events → Evidence corpus: records outcomes (evidence: `src/lib/learningEvents.ts`)
- NEXUS convergence → Evidence corpus: converges evidence
- Browser workspace → Browser storage: persists workspace state (evidence: `src/App.tsx`)
- Autonomy policy → Browser storage: persists decision ledger