Skip to content
JamieAPPublic

About

OpenTelemetry tracing for Claude Code and Codex, with a Rust CLI, MCP queries and local or Cloudflare collectors.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Gently logo

gently

See your agent's work, one trace at a time.
OpenTelemetry traces for Claude Code and Codex.

Get started · Run locally · MCP · Docs · Contribute

Gently turns coding-agent hooks into a timeline of sessions, turns, tool calls and subagents. Investigate a slow run, follow delegated work, or query recorded activity from the command line and through MCP.

  • Capture locally. Hooks write to a SQLite outbox, so events can queue before a collector or its token is available.
  • Follow the work. Inspect tool durations, completion status, and the span tree behind a session.
  • Query from your agent. Read the same traces through MCP, with filters and JSON output. Raw content capture and resolution are opt-in.

Run the included collector locally or on Cloudflare. It is a Worker backed by D1; the Rust CLI exports OTLP/JSON to it.

A session at a glance

A synthetic session rendered by gently trace --waterfall:

      dur st  span                      │timeline →                                              │
────────── ─  ──────────────────────────┼────────────────────────────────────────────────────────┤
  1000.0ms ✓  session                   │████████████████████████████████████████████████████████│
   900.0ms ✓    turn:1                  │   ██████████████████████████████████████████████████   │
    20.0ms ✓      Read                  │    █                                                   │
   200.0ms ✗      Bash                  │      ███████████                                       │
   450.0ms ✓      agent:1               │                      █████████████████████████         │
   300.0ms ·        Bash                │                         █████████████████              │

Status: ✓ ok · unset ✗ error ? unknown

Current support

Capture and queries cover Claude Code and Codex coding agents in the terminal and desktop. On Unix, desktop MCP can delegate queries to an unlocked export watcher through a private socket. See compatibility for checked versions, hook coverage and fidelity limits.

Read data and privacy before enabling capture.

Quick start

You need Rust and Cargo, Node.js and npm. Deploying to Cloudflare also requires an account authenticated with Wrangler. Start from a source checkout:

git clone https://github.com/JamieAP/gently.git
cd gently

1. Deploy a collector

cd worker
npm ci --ignore-scripts
npx wrangler d1 create gently

Copy the returned database ID into wrangler.toml, then initialize the database, enroll per-host bearer credentials, and deploy:

npx wrangler d1 execute gently --remote --file schema.sql
npx wrangler d1 migrations apply gently --remote
npx wrangler secret put GENTLY_HOSTS
npx wrangler deploy
cd ..

Configure GENTLY_HOSTS through a private secret-provider workflow as a JSON array of {token, tenant_id, device_id, capabilities} records. Use distinct host credentials and ingest/read capabilities; keep credential values out of source and shell arguments. See collector setup.

For a local collector, follow local setup. The launchers accept an inherited token from your provider on Macs or Linux and start a loopback Worker, local D1 and an export watcher. A separate Mac hardware-backed secret helper is an optional wrapper.

2. Install the hooks

Install a release build (macOS on Apple silicon or x86_64 Linux, checksummed with build provenance), or build from source:

cargo install --path crates/gently-cli --locked
gently init --claude
# For Codex instead: gently init --codex

Init installs the hooks and MCP server and creates ~/.gently/config.toml if it is missing. Set the collector URL and enrolled tenant/device there. Supply the process's bearer credential only as GENTLY_TOKEN to export and query processes:

collector_url = "https://gently-collector.<account>.workers.dev"
tenant_id = "personal"
device_id = "mac-main"
# prefer_quic = true

Restart your agent session after configuring it. Codex hooks must also be trusted inside Codex. GENTLY_COLLECTOR_URL, GENTLY_TENANT_ID and GENTLY_DEVICE_ID override public config values; GENTLY_TOKEN has no persisted-token fallback. See configuration for queue, transport, timeout, and state-directory options. A watcher can export tokenless desktop hooks. With --serve-queries, it also handles tokenless CLI/MCP queries over an owner-only Unix socket. Background hooks never attempt hardware unlock.

3. Query a session

Run a task in the configured agent, then inspect its captured activity:

gently traces
gently trace TRACE_ID
gently spans --tool-name Bash
gently stats
gently status

Replace TRACE_ID with an ID from gently traces. Trace queries read from the collector; gently status reports local capture, recipient-policy and export health.

To render a trace timeline with integrity checks:

gently trace TRACE_ID --waterfall

For saved or piped span JSON, use gently waterfall < trace.json. Neither waterfall command requires Python.

MCP

The MCP server is built into the CLI as gently mcp. Both init commands above register it with the chosen agent. Restart the agent to load the registration; for Claude Code, check it with claude mcp get gently.

Tool Purpose
list_traces Find sessions and traces
get_trace Read a trace's spans
search_spans Filter recorded spans
trace_stats Summarize tool usage
response_fields Inspect available response fields
span_attr_keys Discover recorded attribute keys

The server uses stdio and its tools are read-only. Queries return metadata, byte lengths and optional opaque raw references by default. See querying and MCP for arguments, ordering, and local jq filters.

Data and privacy

Normal exports contain metadata and byte lengths, with no public content fingerprints. Optional raw fields are encrypted before local persistence to only the readers in an owner-signed, locally pinned tenant policy. Capture, ciphertext cloud sync and reader resolution are independent and disabled by default. Cloudflare receives opaque ciphertext and never a raw-decryption key.

Enroll Mac/Linux readers, including a recovery device, before enabling capture. Readers unlock their identity only for explicit resolution; decrypted CLI/MCP output can enter the calling agent's model-provider context. Native Mac hardware keys and passphrase-encrypted software keys have different protection guarantees.

The collector maps host credentials to tenant/device and ingest/read rights. Tenant boundaries are enforced in all storage and queries. Paths, host data, byte lengths and activity patterns remain visible, and raw objects have no writer signatures or full replay/provenance protocol against a malicious cloud. There is no automatic retention. Read security and privacy for those limits.

Gently 1.0 accepts only its encrypted local schema. Supported encrypted state opens without a reset, and future schema changes ship with reviewed migrations or an explicit version refusal. Plaintext state from early development builds is rejected, not migrated: reset it explicitly. The separate credential vault is preserved.

Architecture and documentation

One trace represents a session. Turns, tools, and subagents form its span tree. Hooks queue one OTLP/JSON envelope per event. With a collector token, they start a detached exporter; tokenless hooks queue locally. gently export --watch drains the queue continuously and reuses connections. Remote export can use HTTP/3, with a TCP fallback.

The exporter drains the outbox with retry and backoff. All exports preserve queued history by default. --discard-oldest explicitly opts into dropping excess oldest envelopes at the configured outbox_cap before each drain. Queue storage can grow without a limit when history is preserved. Authentication failures stop export immediately; transient failures use backoff, and unprocessable envelopes can be quarantined.

Session, turn, and subagent spans are updated as they open and close. The Worker merges repeated span reports within a tenant and preserves each span's capture device ownership. Exporting to another OpenTelemetry backend requires handling these updates; CLI and MCP queries also depend on the Worker's query API.

Claude Code / Codex hooks -> local SQLite outbox -> Worker -> D1
                                                   ^
                                              CLI and MCP

Development

The Rust workspace is in crates/, the collector in worker/, and local collector helpers in scripts/.

Install the public-repository Git gates in every development checkout:

git config --local core.hooksPath .githooks

After reviewing the exact change for public disclosure, acknowledge each command with GENTLY_PUBLIC_REPO_SANITY=1 git commit ... or GENTLY_PUBLIC_REPO_SANITY=1 git push .... The acknowledgement does not bypass checks. The gates inspect staged files, commit messages and complete outgoing history, including deleted files and annotated tags. Captured hook/OTLP JSON, encrypted raw objects, credentials, private state, databases, archives and local home paths are rejected; diagnostics withhold matched values. Keep all runtime state outside tracked files and review other confidential prose or code manually.

cargo test
cargo clippy --all-targets -- -D warnings
cd worker
npm ci --ignore-scripts
npm test
npm run typecheck

Read the capture and privacy documentation before enabling selected raw fields. The old plaintext full-payload debug capture has been removed.

License

MIT. Dependencies retain their own licenses and notices.

About

OpenTelemetry tracing for Claude Code and Codex, with a Rust CLI, MCP queries and local or Cloudflare collectors.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages