> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/local-agent-contract.md). # Local Agent Contract AI OS exposes local AI agent telemetry through the browser-safe `localAgents` branch in live data. The branch is provider-neutral so Claude Code and OpenAI Codex can be represented side by side without treating Codex data as Claude activity. Trend Finder remains a repo-local extension and does not own this contract. `localAgents` is AI OS host telemetry. ## Access And Delivery Contract AI OS local agent goals default to full local access, write access, and edit access. Metadata-only inventory is allowed when a parser or scanner is the shipped feature, but it must not be used to imply that a write, edit, shell, process, OAuth, marketplace, or turn-control capability has shipped. Any local-agent capability exposed as a product action must prove real execution, visible results, recovery states, and tests. Until then, document it as metadata-only or deferred instead of as complete. ## Shape `localAgents` is a required top-level `LiveData` key: ``` localAgents schemaVersion generatedAt providers sessions workspaces usage configSources integrationSources memorySources skillSources automationSources compatibilityAliases ``` The contract is additive. Existing top-level branches such as `usage.claudeWindow`, `usage.chatgptWindow`, `activity`, `recentProjects`, `skills`, `integrations`, `automations`, `memory`, and subscriptions remain readable while route consumers migrate. ## Providers Provider entries live under `localAgents.providers` and are keyed by provider ID. The current known IDs are: * `claude` for Claude Code host telemetry. * `codex` for OpenAI Codex host telemetry. Future provider keys are allowed when the value follows the provider snapshot shape. The validator preserves usable future provider objects and backfills known Claude and Codex defaults when missing. Provider readiness uses explicit states: * `ready` means telemetry is present and usable. * `degraded` means telemetry exists but part of the source could not be read or exceeded a scan limit. * `missing` means the source was not found. * `empty` means the source exists but has no usable child records yet. * `pending` means a later session owns the parser or auth normalization. * `unknown` means the state could not be classified safely. ## Source Summaries Source arrays summarize browser-safe metadata only: * `configSources` * `integrationSources` * `memorySources` * `skillSources` * `automationSources` Rows include provider ID, kind, label, readiness status, count, last-updated metadata, and small primitive metadata. They must not include raw config files, auth payloads, prompts, transcript bodies, command output, or unredacted local paths. Each source row uses these implemented fields: * `id` * `providerId` * `kind` * `label` * `status` * `count` * `lastUpdatedAt` * `lastUpdatedAgo` * `metadata` `metadata` is limited to primitive values: strings, numbers, booleans, and null. ## Implemented Assembly The aggregate script builds `localAgents` through `scripts/lib/local-agent-assembly.ts` before write validation. Claude projection currently uses existing legacy aggregate facts: * parsed project activity * activity runs and outputs * Claude usage windows * model usage counts * skill, automation, integration, and memory summary counts Claude usage windows expose a `source` and `statusText`. `source: "oauth"` means exact OAuth usage was fetched from Anthropic's OAuth usage endpoint. `source: "estimate"` means the window is estimated from local Claude logs because exact OAuth usage was unavailable. Local estimates are acceptable for development dashboards, but they are not plan-authoritative. Codex projection currently uses Session 01 safe inventory metadata: * home and child readiness status * child file and directory counts * latest modified timestamps * traversal limits and truncated/degraded counts Codex projection also uses Session 03 session/history metadata: * safe session and workspace rows * message, tool-call, error, model-label, and command/tool-class counts * malformed, unsupported, and truncated row counts Session 04 adds separated OpenAI/Codex auth and usage facts: * ChatGPT plan presence * OpenAI API key readiness * Codex CLI auth readiness * configured and observed model labels * explicit unknown pricing when token accounting is unavailable * maintained Claude Fable 5 pricing for API-equivalent Claude usage totals Session 05 adds parser-backed Codex config inventory: * global `CODEX_HOME/config.toml` status * current repo `.codex/config.toml` status * MCP, app, connector, plugin, and model-provider integration counts * configured model, reasoning, verbosity, sandbox, approval, permission, web search, shell environment, and project trust policy counts * skill, hook, memory, and multi-agent declaration counts Session 06 adds metadata-only Codex memory, instruction, skill, and automation parity: * `CODEX_HOME/memory` and `CODEX_HOME/memories` source counts * current project `AGENTS.md` and `.codex` metadata counts * external-agent import container counts * shell snapshot container counts * installed and used Codex skill counts from `CODEX_HOME` roots * Codex automation rows from parser-backed `automation.toml` metadata Provider-neutral visible UI parity is implemented in Session 07. Optional Codex app-server readiness is implemented in Session 08. ## Codex Session And History Scanner Codex session scanning is implemented in `scripts/lib/codex-session-scanner.ts`. It resolves paths through the `CODEX_HOME` helpers at scan time and falls back to `~/.codex` when no override is configured. The scanner reads only: * `CODEX_HOME/sessions/**/*.jsonl` * `CODEX_HOME/history.jsonl` Rows are parsed only when they are JSON objects. The scanner allowlists metadata fields for session/conversation/thread IDs, timestamps, roles, statuses, workspace hints, model labels, tool hints, and command hints. Tool and command values are reduced to broad classes such as `shell`, `file edit`, `search`, `browser`, `network`, `mcp`, `image`, `git`, `test`, `typecheck`, `build`, `quality`, `filesystem`, and `package manager`. The scanner emits provider/source status, session counts, message counts, error counts, tool-call counts, timestamps, model labels, tool classes, command classes, sanitized workspace leaf labels, and scanner totals for rows, malformed rows, unsupported rows, truncation, and source file counts. It does not emit raw prompts, responses, transcript bodies, command text, command output, diffs, patches, logs, auth payloads, account identifiers, file contents, or absolute private paths. Default scan limits are: | Limit | Default | | ------------------- | ------- | | Directory depth | 5 | | Session JSONL files | 60 | | Bytes per file | 524288 | | Lines per file | 2000 | | Emitted sessions | 100 | | Emitted workspaces | 100 | | History rows | 2000 | Missing sources produce `missing` status. Empty directories produce `empty` status. Unreadable paths, unexpected file kinds, malformed rows, unsupported rows, and limit truncation do not crash aggregation; they increment totals, add warnings, and may set the scanner status to `degraded`. Large local Codex histories are intentionally bounded instead of read completely. On machines with thousands of session files or multi-gigabyte session logs, the aggregate reads a capped sample and reports partial data through scanner warnings, aggregate log lines, provider metadata, and dashboard data-quality rows. Warning codes include the reached cap, such as session file, directory depth, per-file byte, per-file line, emitted session, and history row limits. Unknown token accounting and pricing are not inferred from session/history files. Auth, usage, model normalization, and pricing semantics are handled by separate Codex/OpenAI aggregate modules. When a Claude session model has a maintained price, aggregate model usage includes that cost in daily, API-equivalent, and value totals. Claude Fable 5 uses the maintained Anthropic rate row in `scripts/lib/session-scanner.ts`. When an observed model is still unknown, `modelUsage` and `modelSplit` keep the model in an explicit unknown pricing bucket with excluded token and message counts; aggregate logs state that cost and value totals remain priced-only until a maintained rate is added. ## Codex Config Inventory Codex config parsing is implemented in `scripts/lib/codex-config-parser.ts`. The parser reads only: * the resolved `CODEX_HOME/config.toml` * this repository's `.codex/config.toml` It does not walk arbitrary project paths from config. Project trust entries are reported as counts only. The parser emits source snapshots and bounded rows. Rows contain only safe primitive metadata such as: * source kind * row kind * label and slug after redaction checks * enabled/readiness state * transport class * counts * boolean presence flags The parser intentionally does not emit: * command strings or args * env values or env key names * headers * raw URLs * provider credential fields * private absolute paths * auth payloads * hook bodies * memory bodies * skill bodies * prompts, transcripts, command output, diffs, or logs Malformed, unreadable, absent, and non-file config paths degrade to explicit source statuses instead of failing aggregation. ## Codex Memory, Skills, And Automations Codex memory and instruction scanning is implemented in `scripts/lib/codex-memory-scanner.ts`. The scanner inspects only metadata for: * `CODEX_HOME/memory` * `CODEX_HOME/memories` * `CODEX_HOME/shell_snapshots` * selected external-agent import containers under `CODEX_HOME` * this repository's `AGENTS.md` * this repository's `.codex` metadata directory It emits bounded source snapshots with: * source id, kind, label, and safe path label * status * file and directory counts * latest modified timestamp * truncation and degradation flags It intentionally does not emit: * memory bodies * instruction bodies * shell snapshot bodies * external-agent import bodies * raw local paths * transcript text, prompts, command output, diffs, logs, or credentials Codex skill scanning continues to use `scripts/lib/skill-scanner.ts`. Codex usage roots and installed skill roots resolve from `CODEX_HOME`; Claude roots remain supported. Skill rows expose only command names, usage counts, timestamps, and source labels. Codex automation scanning uses parser-backed TOML handling in `scripts/lib/automation-scanner.ts`. Automation rows expose only safe name, cadence, status, source, and allowlisted model metadata. Command bodies, env values, credential-like labels, raw private paths, prompts, and outputs are not emitted. Malformed Codex automation TOML degrades to a stable failed metadata row rather than failing aggregation. Session 07 adds provider-neutral UI and setup parity for local-agent provider filters, diagnostics, route copy, setup detection, and settings views. ## Codex App-Server Readiness Session 08 adds optional Codex app-server readiness metadata: * `CODEX_APP_SERVER_URL` is consumed only by Bun aggregation scripts. * Missing endpoint configuration is a normal `missing` state for CLI-only setups. * Aggregate console output labels this as optional and names the setup variable: set `CODEX_APP_SERVER_URL` to an explicit loopback `http://` or `ws://` endpoint only when app-server metadata is intentionally needed. * Endpoint parsing accepts only explicit loopback `http://` and `ws://` URLs. * Rejected, unavailable, timeout, auth-required, unsupported, and degraded states stay visible without failing aggregation. * Provider snapshots may include `providers.codex.appServer`, a browser-safe readiness object. * Codex provider summaries expose separate app-server counters such as loaded threads, models, apps, plugins, MCP servers, MCP tools, and MCP resources. * `integrationSources` includes `codex-app-server-readiness` with status, health, RPC status, warning count, and count metadata. The app-server scanner does not start Codex, spawn processes, open stdio transport, execute commands, start or steer turns, resume or fork threads, write config, install plugins, write app settings, run OAuth login/logout, read files, import external-agent data, or emit raw thread, turn, prompt, transcript, command output, diff, or file content. The endpoint must be an explicit loopback `http://` or `ws://` URL. Public, private-LAN, VPN, hostname, credentialed, path-bearing, query-bearing, and fragment-bearing endpoints are rejected before any request is attempted. Status meanings: | State | Meaning | Operator action | | --------------- | ----------------------------------------------------- | --------------------------------------------------------------- | | `missing` | No endpoint configured | Nothing required | | `rejected` | Endpoint was malformed, credentialed, or non-loopback | Use a loopback URL or unset the variable | | `unavailable` | Endpoint did not accept a health request | Start Codex yourself or leave it absent | | `timeout` | Health request exceeded the scanner timeout | Check the listener if it should be running | | `auth_required` | WebSocket handshake or RPC metadata requires auth | Leave metadata unavailable until scoped auth exists | | `unsupported` | Endpoint class is outside this readiness MVP | Use loopback HTTP/WebSocket health probing | | `degraded` | Partial health or RPC metadata was collected | Inspect warnings, then leave metadata unavailable if acceptable | | `ready` | Health and optional counts were collected | No action required | When changing readiness behavior, run the normal local aggregate and test flow: ```bash bun run aggregate bun run typecheck bun run typecheck:scripts bun run test ``` ## Privacy Boundary Aggregation may inspect local agent files through bounded metadata scanners, but `localAgents` emits only sanitized summaries: * statuses * counts * timestamps * redacted labels * safe provider and source categories Codex config, memory, skill, automation, and app-server readiness inventory follows the same boundary. Secret-bearing labels are redacted or skipped from top-level rows, while parser and scanner totals still record safe counts and degraded states. Private runtime files remain local. `src/data/live-data.json` is generated and gitignored. The committed fallback `src/data/live-data.example.json` contains only fixture-safe values. ## Compatibility Aliases `localAgents.compatibilityAliases` records legacy fields that stay readable during migration: * `usage.claudeWindow` maps to Claude usage summaries. * `usage.chatgptWindow` maps to Codex/ChatGPT usage summaries while route consumers migrate to provider-neutral usage rows. * `activity` maps to Claude-derived local-agent sessions. * `recentProjects` maps to Claude-derived local-agent workspaces. * `skills.active` maps to provider-neutral skill sources. These aliases are read compatibility, not a promise that the legacy field names will be used for new UI. New or migrated route consumers should use `localAgents` directly instead of adding new dependencies on legacy branch names. Alias lifecycle: * `active` means the legacy field is still emitted and should stay readable. * `deprecated` is reserved for a later migration stage after route consumers stop depending on the alias. * `planned` is reserved for future aliases that are documented before the corresponding provider data lands. ## Deferred Work Future work remains separate from the implemented metadata contract until each capability has real execution, visible results, recovery states, and tests: * ChatGPT Apps surfaces. * Responses API runtime integration. * Agents SDK runtime integration. * App-server write, turn-control, command, process, filesystem, marketplace, OAuth, external-agent import, and config mutation flows. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/local-agent-contract.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.