# theunknownport/aight-clients architecture

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

- Interactive diagram: https://gitdiagram.com/theunknownport/aight-clients
- Repository: https://github.com/theunknownport/aight-clients

## Overview

AIght SDKs record LLM usage against the caller’s source location, aggregate token and cache counts, and send spans, reported value, and business events to the AIght Workspace. Python and Node also offer provider auto-instrumentation; Go and Java provide opt-in HTTP wrapping. Python’s collectors read external agents’ local records, while its proxy observes and forwards API traffic. The graph groups parallel language implementations; unsampled subsystems are included only where the README documents them, with uncertain wiring omitted.

Main entry points: [`python/aight/collect/base.py`](https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/base.py) (Collector workflow), [`python/aight/collect/proxy.py`](https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/proxy.py) (Traffic proxy), [`python/aight/remote.py`](https://github.com/theunknownport/aight-clients/blob/main/python/aight/remote.py) (Python delivery), [`node/src/remote.js`](https://github.com/theunknownport/aight-clients/blob/main/node/src/remote.js) (Node delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["Tracing SDKs"]
  node_pytrace["Python tracing<br/>[tracing.py]"]
  node_nodetrace["Node tracing<br/>[tracing.js]"]
  node_gotrace["Go tracing<br/>[tracing.go]"]
  node_javatrace["Java tracing<br/>[Tracing.java]"]
end

subgraph group_delivery["Data Delivery"]
  node_pyremote["Python delivery<br/>[remote.py]"]
  node_noderemote["Node delivery<br/>[remote.js]"]
  node_goremote["Go delivery<br/>[remote.go]"]
  node_javaremote["Java delivery<br/>[Remote.java]"]
end

subgraph group_external["External Spend"]
  node_collectorbase["Collector workflow<br/>[base.py]"]
  node_claude["Claude collector<br/>[claude_code.py]"]
  node_codex["Codex collector<br/>[codex.py]"]
  node_gemini["Gemini collector<br/>[gemini.py]"]
  node_aider["Aider collector<br/>[aider.py]"]
  node_proxy["Traffic proxy<br/>[proxy.py]"]
end

subgraph group_instrumentation["Provider Instrumentation"]
  node_pyauto["Python auto-instrument<br/>[auto.py]"]
  node_nodeauto["Node auto-instrument<br/>[auto.js]"]
  node_goauto["Go HTTP wrapper<br/>[auto.go]"]
  node_javaauto["Java HTTP wrapper"]
end

node_developer(("Application developer"))
node_workspace[("AIght Workspace API")]
node_localrecords["Agent local records"]
node_agent(("External agent"))
node_provider{{"LLM provider API"}}

node_developer -->|"records calls"| node_pytrace
node_developer -->|"records calls"| node_nodetrace
node_developer -->|"records calls"| node_gotrace
node_developer -->|"records calls"| node_javatrace
node_developer -->|"pushes data"| node_pyremote
node_developer -->|"pushes data"| node_noderemote
node_developer -->|"pushes data"| node_goremote
node_developer -->|"pushes data"| node_javaremote
node_pyremote -->|"reads buckets"| node_pytrace
node_noderemote -->|"reads buckets"| node_nodetrace
node_goremote -->|"reads buckets"| node_gotrace
node_javaremote -->|"reads buckets"| node_javatrace
node_pyremote -->|"posts spans, value, events"| node_workspace
node_noderemote -->|"posts ingest data"| node_workspace
node_goremote -->|"posts ingest data"| node_workspace
node_javaremote -->|"posts ingest data"| node_workspace
node_pyauto -->|"records provider spans"| node_pytrace
node_pyauto -.->|"instruments client"| node_provider
node_nodeauto -->|"records provider calls"| node_nodetrace
node_nodeauto -.->|"instruments client"| node_provider
node_developer -->|"configures wrapper"| node_goauto
node_goauto -->|"records responses"| node_gotrace
node_developer -->|"configures wrapper"| node_javaauto
node_javaauto -->|"records responses"| node_javatrace
node_agent -->|"writes sessions"| node_localrecords
node_localrecords -->|"read transcripts"| node_claude
node_localrecords -->|"read sessions"| node_codex
node_localrecords -->|"read sessions"| node_gemini
node_localrecords -->|"read analytics"| node_aider
node_claude -->|"parses records"| node_collectorbase
node_codex -->|"parses records"| node_collectorbase
node_gemini -->|"parses records"| node_collectorbase
node_aider -->|"parses records"| node_collectorbase
node_collectorbase -->|"posts external spans"| node_workspace
node_agent -->|"sends API traffic"| node_proxy
node_proxy -->|"forwards requests"| node_provider
node_provider -->|"returns usage"| node_proxy
node_proxy -->|"pushes usage rows"| node_collectorbase

click node_pytrace "https://github.com/theunknownport/aight-clients/blob/main/python/aight/tracing.py"
click node_nodetrace "https://github.com/theunknownport/aight-clients/blob/main/node/src/tracing.js"
click node_gotrace "https://github.com/theunknownport/aight-clients/blob/main/go/tracing.go"
click node_javatrace "https://github.com/theunknownport/aight-clients/blob/main/java/src/main/java/studio/aight/sdk/Tracing.java"
click node_pyremote "https://github.com/theunknownport/aight-clients/blob/main/python/aight/remote.py"
click node_noderemote "https://github.com/theunknownport/aight-clients/blob/main/node/src/remote.js"
click node_goremote "https://github.com/theunknownport/aight-clients/blob/main/go/remote.go"
click node_javaremote "https://github.com/theunknownport/aight-clients/blob/main/java/src/main/java/studio/aight/sdk/Remote.java"
click node_collectorbase "https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/base.py"
click node_claude "https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/claude_code.py"
click node_codex "https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/codex.py"
click node_gemini "https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/gemini.py"
click node_aider "https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/aider.py"
click node_proxy "https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/proxy.py"
click node_pyauto "https://github.com/theunknownport/aight-clients/blob/main/python/aight/auto.py"
click node_nodeauto "https://github.com/theunknownport/aight-clients/blob/main/node/src/auto.js"
click node_goauto "https://github.com/theunknownport/aight-clients/blob/main/go/auto.go"
click node_javaauto "https://github.com/theunknownport/aight-clients/blob/main/java/src/main/java/studio/aight/sdk/AutoInstrument.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_pytrace,node_nodetrace,node_gotrace,node_javatrace toneBlue
class node_pyremote,node_noderemote,node_goremote,node_javaremote,node_workspace toneAmber
class node_collectorbase,node_claude,node_codex,node_gemini,node_aider,node_proxy,node_provider toneMint
class node_pyauto,node_nodeauto,node_goauto,node_javaauto toneRose
class node_developer,node_localrecords,node_agent toneIndigo
```

## Components

### Tracing SDKs

- [Python tracing](https://github.com/theunknownport/aight-clients/blob/main/python/aight/tracing.py): `python/aight/tracing.py`
- [Node tracing](https://github.com/theunknownport/aight-clients/blob/main/node/src/tracing.js): `node/src/tracing.js`
- [Go tracing](https://github.com/theunknownport/aight-clients/blob/main/go/tracing.go): `go/tracing.go`
- [Java tracing](https://github.com/theunknownport/aight-clients/blob/main/java/src/main/java/studio/aight/sdk/Tracing.java): `java/src/main/java/studio/aight/sdk/Tracing.java`

### Data Delivery

- [Python delivery](https://github.com/theunknownport/aight-clients/blob/main/python/aight/remote.py): `python/aight/remote.py`
- [Node delivery](https://github.com/theunknownport/aight-clients/blob/main/node/src/remote.js): `node/src/remote.js`
- [Go delivery](https://github.com/theunknownport/aight-clients/blob/main/go/remote.go): `go/remote.go`
- [Java delivery](https://github.com/theunknownport/aight-clients/blob/main/java/src/main/java/studio/aight/sdk/Remote.java): `java/src/main/java/studio/aight/sdk/Remote.java`

### External Spend

- [Collector workflow](https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/base.py): `python/aight/collect/base.py`
- [Claude collector](https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/claude_code.py): `python/aight/collect/claude_code.py`
- [Codex collector](https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/codex.py): `python/aight/collect/codex.py`
- [Gemini collector](https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/gemini.py): `python/aight/collect/gemini.py`
- [Aider collector](https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/aider.py): `python/aight/collect/aider.py`
- [Traffic proxy](https://github.com/theunknownport/aight-clients/blob/main/python/aight/collect/proxy.py): `python/aight/collect/proxy.py`

### Provider Instrumentation

- [Python auto-instrument](https://github.com/theunknownport/aight-clients/blob/main/python/aight/auto.py): `python/aight/auto.py`
- [Node auto-instrument](https://github.com/theunknownport/aight-clients/blob/main/node/src/auto.js): `node/src/auto.js`
- [Go HTTP wrapper](https://github.com/theunknownport/aight-clients/blob/main/go/auto.go): `go/auto.go`
- [Java HTTP wrapper](https://github.com/theunknownport/aight-clients/blob/main/java/src/main/java/studio/aight/sdk/AutoInstrument.java): `java/src/main/java/studio/aight/sdk/AutoInstrument.java`

### Other components

- **Application developer**
- **AIght Workspace API**
- **Agent local records**
- **External agent**
- **LLM provider API**

## Connections

- Application developer → Python tracing: records calls
- Application developer → Node tracing: records calls
- Application developer → Go tracing: records calls
- Application developer → Java tracing: records calls
- Application developer → Python delivery: pushes data
- Application developer → Node delivery: pushes data
- Application developer → Go delivery: pushes data
- Application developer → Java delivery: pushes data
- Python delivery → Python tracing: reads buckets
- Node delivery → Node tracing: reads buckets
- Go delivery → Go tracing: reads buckets
- Java delivery → Java tracing: reads buckets
- Python delivery → AIght Workspace API: posts spans, value, events
- Node delivery → AIght Workspace API: posts ingest data
- Go delivery → AIght Workspace API: posts ingest data
- Java delivery → AIght Workspace API: posts ingest data
- Python auto-instrument → Python tracing: records provider spans
- Python auto-instrument → LLM provider API: instruments client
- Node auto-instrument → Node tracing: records provider calls
- Node auto-instrument → LLM provider API: instruments client
- Application developer → Go HTTP wrapper: configures wrapper
- Go HTTP wrapper → Go tracing: records responses
- Application developer → Java HTTP wrapper: configures wrapper
- Java HTTP wrapper → Java tracing: records responses
- External agent → Agent local records: writes sessions
- Agent local records → Claude collector: read transcripts
- Agent local records → Codex collector: read sessions
- Agent local records → Gemini collector: read sessions
- Agent local records → Aider collector: read analytics
- Claude collector → Collector workflow: parses records
- Codex collector → Collector workflow: parses records
- Gemini collector → Collector workflow: parses records
- Aider collector → Collector workflow: parses records
- Collector workflow → AIght Workspace API: posts external spans
- External agent → Traffic proxy: sends API traffic
- Traffic proxy → LLM provider API: forwards requests
- LLM provider API → Traffic proxy: returns usage
- Traffic proxy → Collector workflow: pushes usage rows