# noblehacks/frenemy architecture

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

- Interactive diagram: https://gitdiagram.com/noblehacks/frenemy
- Repository: https://github.com/noblehacks/frenemy

## Overview

Frenemy connects Claude Code, Codex, Antigravity/Gemini, and Kimi so whichever app the user is using can request advice or delegate work. The README describes those capabilities; the available source excerpts do not show the main relay or provider MCP implementations, so their detailed call flow is left unasserted. Real-work isolation is implemented by the worker workspace. Snitch is a separate VS Code panel backed by shared job records and hooks. The graph preserves these branches while limiting source-backed edges to visible references and documented behavior.

Main entry points: [`snitch/bin/fleet.mjs`](https://github.com/noblehacks/frenemy/blob/main/snitch/bin/fleet.mjs) (Job records), [`snitch/bin/run-job.mjs`](https://github.com/noblehacks/frenemy/blob/main/snitch/bin/run-job.mjs) (Job runner), [`snitch/hooks/beat-lib.mjs`](https://github.com/noblehacks/frenemy/blob/main/snitch/hooks/beat-lib.mjs) (Activity hooks), [`snitch/extension/extension.js`](https://github.com/noblehacks/frenemy/blob/main/snitch/extension/extension.js) (VS Code panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ai["AI interfaces"]
  node_claude{{"Claude Code"}}
  node_codex{{"Codex"}}
  node_gemini{{"Gemini / agy"}}
  node_kimi{{"Kimi Code"}}
  node_claude_mcp["Claude tools<br/>[ask-claude-mcp.mjs]"]
  node_codex_mcp["Codex tools<br/>[ask-codex-mcp.mjs]"]
  node_agy_mcp["Antigravity tools<br/>[ask-agy-mcp.mjs]"]
  node_kimi_mcp["Kimi tools<br/>[ask-kimi-mcp.mjs]"]
  node_relay["Relay orchestration<br/>[relay-core.mjs]"]
end

subgraph group_work["Delegated work"]
  node_worker["Worker workspace"]
  node_guard["Worker safeguards<br/>[worker-guard.mjs]"]
  node_image["Image delivery"]
end

subgraph group_snitch["Snitch monitoring"]
  node_fleet[("Job records<br/>[fleet.mjs]")]
  node_runjob["Job runner<br/>[run-job.mjs]"]
  node_beats["Activity hooks<br/>[beat-lib.mjs]"]
  node_panel["VS Code panel<br/>[extension.js]"]
  node_jobmodel["Job view model<br/>[model.js]"]
  node_archive["Job archiving<br/>[archive-jobs.js]"]
end

subgraph group_shared["Shared runtime"]
  node_lock["Shared job locks<br/>[joblock.js]"]
  node_platform["Process platform<br/>[platform.mjs]"]
end

node_user(("User"))
node_driver(("AI driver"))

node_user -->|"gives request"| node_driver
node_driver -.->|"uses tools"| node_claude_mcp
node_driver -.->|"uses tools"| node_codex_mcp
node_driver -.->|"uses tools"| node_agy_mcp
node_driver -.->|"uses tools"| node_kimi_mcp
node_driver -.->|"delegates work"| node_relay
node_relay -.->|"prepares and applies"| node_worker
node_worker -.->|"checks safeguards"| node_guard
node_driver -.->|"requests image delivery"| node_image
node_runjob -->|"records job status"| node_fleet
node_beats -->|"updates job activity"| node_fleet
node_panel -->|"builds job view"| node_jobmodel
node_panel -->|"archives jobs"| node_archive
node_archive -->|"locks job updates"| node_lock
node_runjob -->|"launches processes"| node_platform
node_fleet -->|"uses platform helpers"| node_platform
node_beats -->|"reads job helpers"| node_fleet

click node_claude_mcp "https://github.com/noblehacks/frenemy/blob/main/tools/ask-claude-mcp.mjs"
click node_codex_mcp "https://github.com/noblehacks/frenemy/blob/main/tools/ask-codex-mcp.mjs"
click node_agy_mcp "https://github.com/noblehacks/frenemy/blob/main/tools/ask-agy-mcp.mjs"
click node_kimi_mcp "https://github.com/noblehacks/frenemy/blob/main/tools/ask-kimi-mcp.mjs"
click node_relay "https://github.com/noblehacks/frenemy/blob/main/tools/relay-core.mjs"
click node_worker "https://github.com/noblehacks/frenemy/blob/main/tools/worker-workspace.mjs"
click node_guard "https://github.com/noblehacks/frenemy/blob/main/tools/worker-guard.mjs"
click node_image "https://github.com/noblehacks/frenemy/blob/main/tools/agy-image-delivery.mjs"
click node_fleet "https://github.com/noblehacks/frenemy/blob/main/snitch/bin/fleet.mjs"
click node_runjob "https://github.com/noblehacks/frenemy/blob/main/snitch/bin/run-job.mjs"
click node_beats "https://github.com/noblehacks/frenemy/blob/main/snitch/hooks/beat-lib.mjs"
click node_panel "https://github.com/noblehacks/frenemy/blob/main/snitch/extension/extension.js"
click node_jobmodel "https://github.com/noblehacks/frenemy/blob/main/snitch/extension/lib/model.js"
click node_archive "https://github.com/noblehacks/frenemy/blob/main/snitch/extension/lib/archive-jobs.js"
click node_lock "https://github.com/noblehacks/frenemy/blob/main/snitch/extension/lib/joblock.js"
click node_platform "https://github.com/noblehacks/frenemy/blob/main/tools/platform.mjs"

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_claude,node_codex,node_gemini,node_kimi,node_claude_mcp,node_codex_mcp,node_agy_mcp,node_kimi_mcp,node_relay,node_user toneBlue
class node_worker,node_guard,node_image toneAmber
class node_fleet,node_runjob,node_beats,node_panel,node_jobmodel,node_archive toneMint
class node_lock,node_platform toneRose
class node_driver toneIndigo
```

## Components

### AI interfaces

- **Claude Code**
- **Codex**
- **Gemini / agy**
- **Kimi Code**
- [Claude tools](https://github.com/noblehacks/frenemy/blob/main/tools/ask-claude-mcp.mjs): `tools/ask-claude-mcp.mjs`
- [Codex tools](https://github.com/noblehacks/frenemy/blob/main/tools/ask-codex-mcp.mjs): `tools/ask-codex-mcp.mjs`
- [Antigravity tools](https://github.com/noblehacks/frenemy/blob/main/tools/ask-agy-mcp.mjs): `tools/ask-agy-mcp.mjs`
- [Kimi tools](https://github.com/noblehacks/frenemy/blob/main/tools/ask-kimi-mcp.mjs): `tools/ask-kimi-mcp.mjs`
- [Relay orchestration](https://github.com/noblehacks/frenemy/blob/main/tools/relay-core.mjs): `tools/relay-core.mjs`

### Delegated work

- [Worker workspace](https://github.com/noblehacks/frenemy/blob/main/tools/worker-workspace.mjs): `tools/worker-workspace.mjs`
- [Worker safeguards](https://github.com/noblehacks/frenemy/blob/main/tools/worker-guard.mjs): `tools/worker-guard.mjs`
- [Image delivery](https://github.com/noblehacks/frenemy/blob/main/tools/agy-image-delivery.mjs): `tools/agy-image-delivery.mjs`

### Snitch monitoring

- [Job records](https://github.com/noblehacks/frenemy/blob/main/snitch/bin/fleet.mjs): `snitch/bin/fleet.mjs`
- [Job runner](https://github.com/noblehacks/frenemy/blob/main/snitch/bin/run-job.mjs): `snitch/bin/run-job.mjs`
- [Activity hooks](https://github.com/noblehacks/frenemy/blob/main/snitch/hooks/beat-lib.mjs): `snitch/hooks/beat-lib.mjs`
- [VS Code panel](https://github.com/noblehacks/frenemy/blob/main/snitch/extension/extension.js): `snitch/extension/extension.js`
- [Job view model](https://github.com/noblehacks/frenemy/blob/main/snitch/extension/lib/model.js): `snitch/extension/lib/model.js`
- [Job archiving](https://github.com/noblehacks/frenemy/blob/main/snitch/extension/lib/archive-jobs.js): `snitch/extension/lib/archive-jobs.js`

### Shared runtime

- [Shared job locks](https://github.com/noblehacks/frenemy/blob/main/snitch/extension/lib/joblock.js): `snitch/extension/lib/joblock.js`
- [Process platform](https://github.com/noblehacks/frenemy/blob/main/tools/platform.mjs): `tools/platform.mjs`

### Other components

- **User**
- **AI driver**

## Connections

- User → AI driver: gives request (evidence: `README.md`)
- AI driver → Claude tools: uses tools (evidence: `README.md`)
- AI driver → Codex tools: uses tools (evidence: `README.md`)
- AI driver → Antigravity tools: uses tools (evidence: `README.md`)
- AI driver → Kimi tools: uses tools (evidence: `README.md`)
- AI driver → Relay orchestration: delegates work
- Relay orchestration → Worker workspace: prepares and applies
- Worker workspace → Worker safeguards: checks safeguards
- AI driver → Image delivery: requests image delivery
- Job runner → Job records: records job status (evidence: `snitch/bin/run-job.mjs`)
- Activity hooks → Job records: updates job activity (evidence: `snitch/hooks/beat-lib.mjs`)
- VS Code panel → Job view model: builds job view (evidence: `snitch/extension/extension.js`)
- VS Code panel → Job archiving: archives jobs (evidence: `snitch/extension/extension.js`)
- Job archiving → Shared job locks: locks job updates (evidence: `snitch/extension/lib/archive-jobs.js`)
- Job runner → Process platform: launches processes (evidence: `snitch/bin/run-job.mjs`)
- Job records → Process platform: uses platform helpers (evidence: `snitch/bin/fleet.mjs`)
- Activity hooks → Job records: reads job helpers (evidence: `snitch/hooks/beat-lib.mjs`)
