Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.klarity.ai/llms.txt

Use this file to discover all available pages before exploring further.

Use these tools when the user asks “what changed?”, “what happened?”, or “why does this run this way?”
ToolWhen to use
get_recent_process_changesWorkspace-wide version-change feed. “What has been edited recently?”
get_recent_process_observationsWorkspace-wide observations feed. Observations are the deviations / exceptions captured by Companion.
get_process_observationsFull rich payload for each observation on a process: step-level content, positive_deviations, negative_deviations, process_mapping. Use this when you need the structured evidence. Optional version filter.
list_process_observationsLightweight listing — observation IDs, timestamps, brief descriptions. Use this to scan before drilling into get_process_observations.
get_observation_activity_timelineThe actual session timeline behind an observation: what the user did, when. The most “primary source” evidence Klarity has. For long sessions, page through with start_timestamp / end_timestamp in HH:MM:SS format — the response surfaces activity_timeline_truncated when the full window doesn’t fit.

​
What an observation is

An observation is a captured deviation or exception from a real session. It is attached to a specific process and version. The activity timeline is the underlying sequence of user actions that produced the observation — clicks, navigations, field entries, with timestamps. If you only call one tool from this group, call get_observation_activity_timeline on a top observation. It is the closest thing the workspace has to a video replay.

​
Common chains

  • State-of-team brief: get_recent_process_changes + get_recent_process_observations → drill into specific processes via fetch
  • Deep-dive on a process: get_process_observations → pick the top 3 by frequency → get_observation_activity_timeline on each
  • Confirm a transformation candidate: list_process_observations for exception volume → get_observation_activity_timeline to confirm the manual pattern with concrete evidence

​
Cite what you find

Observations have timestamps and version pointers. When the user asks “what’s the evidence?”, surface the observation timestamp and the version it was logged against — that’s a citation the user can audit in Klarity.

​
Deviations

Each observation carries the agent’s per-session understanding of how that run compared to the documented process. Per observation, there are two flavors:
  • Positive deviations — places where the user went beyond the documented path in a useful way: a shortcut, a better validation step, a quality-improving move worth promoting.
  • Negative deviations — friction or workarounds: an extra manual step, a retry, a small fix to keep moving.
Both are judgments made in isolation against one session’s activity timeline. Per-session friction often looks routine on its own, so negative_deviations is frequently null on individual observations even when a pattern is present across many sessions.

​
How to use deviations

A single observation gives you the single-session view. The signal most teams want — “the same workaround appears on 4 of 5 captures,” “this retry is systemic” — is cross-observation deviation analysis: the surface-level patterns that only emerge when you aggregate across the observation set for a process. Two paths:
  1. Klarity Advisor does this aggregation natively across the workspace.
  2. MCP-stitched: pull get_observation_activity_timeline across the observation set for the process, then diff against the pinned process version yourself. The MCP exposes everything Advisor reads — the cross-observation pass is what you stitch.