How mlco2/agentic-footprint works
Agentic Footprint measures and attributes coding-agent environmental impact. The principal workflow runs from agent hooks and energy sampling through a local spool or OTLP receiver, into the Rust watch/control plane for validation, attribution, estimation, and session-level aggregation; CLI reports and the debug console present the results. The graph preserves documented capabilities and stages, but several internal links are based on README-level architecture because their implementation was not sampled.
Main entry points: watch.rs Resident watch · lib.rs Event and read store · ingest.rs Spool ingestion · estimator_worker.rs Estimator worker
Components 23
Collection
- Agent collectors
collectors/pi/capture-events.ts - Energy sampler
python/af_sampler
Ingestion
- Local JSONL spool
crates/af-spool/src/lib.rs - OTLP receiver
crates/af-otlp/src/server.rs - Telemetry normalization
crates/af-otlp/src/normalize.rs - Event validation
crates/af-events/src/validate.rs - Spool ingestion
crates/af-cli/src/cmd/ingest.rs - Event and read store
crates/af-store/src/lib.rs
Analysis
- Resident watch
crates/af-cli/src/cmd/watch.rs - Action attribution
crates/af-core/src/attribution.rs - Event correlation
crates/af-core/src/correlate.rs - Impact estimation
python/af_estimator/__main__.py - Estimator worker
crates/af-cli/src/cmd/estimator_worker.rs - Session aggregation
crates/af-store/src/derived.rs
Presentation
- CLI results
crates/af-cli/src/cmd/report.rs - Statusline output
crates/af-cli/src/statusline.rs - Console API client
console/src/lib/client/afClient.svelte.ts - Debug console
console/src/App.svelte - Session selection
console/src/lib/stores/sessionStore.svelte.ts
Operations
- Receiver service
crates/af-cli/src/cmd/service.rs - Managed Python runtime
crates/af-sidecar/src/pyenv.rs
Other components
- Coding agents
- Operator
Connections 28
- Coding agents → Agent collectors: emit facts
README.md - Agent collectors → Local JSONL spool: write events
README.md - Energy sampler → Local JSONL spool: write samples
README.md - Coding agents → OTLP receiver: export telemetry
README.md - OTLP receiver → Telemetry normalization: normalize payloads
crates/af-otlp/src/server.rs - Telemetry normalization → Event and read store: persist facts
README.md - Resident watch → OTLP receiver: run receiver
README.md - Resident watch → Spool ingestion: run ingest pass
crates/af-cli/src/cmd/ingest.rs - Spool ingestion → Local JSONL spool: tail files
crates/af-cli/src/cmd/ingest.rs - Spool ingestion → Event validation: validate events
README.md - Spool ingestion → Event and read store: insert facts
crates/af-cli/src/cmd/ingest.rs - Resident watch → Event and read store: commit updates
- Resident watch → Action attribution: attribute actions
README.md - Action attribution → Event correlation: correlate spans
crates/af-core/src/attribution.rs - Resident watch → Estimator worker: request estimates
README.md - Estimator worker → Impact estimation: estimate impacts
README.md - Estimator worker → Event and read store: return estimate rows
crates/af-cli/src/cmd/estimator_worker.rs - Resident watch → Session aggregation: rebuild summaries
README.md - Event and read store → Session aggregation: supply stored facts
README.md - Operator → CLI results: request results
README.md - CLI results → Event and read store: read session data
README.md - CLI results → Statusline output: render status
README.md - Operator → Debug console: inspect receiver
README.md - Debug console → Console API client: start client
console/src/App.svelte - Console API client → Session selection: update sessions
console/src/lib/client/afClient.svelte.ts - Console API client → Resident watch: fetch debug data
README.md - Receiver service → Resident watch: manage receiver
README.md - Resident watch → Managed Python runtime: supervise runtime
README.md