Skills
A skill is a package of structured files that teaches an AI coding agent how to work with a specific tool or framework. The skill below was generated by Great Docs from this project’s documentation. Install it in your agent and it will be able to run commands, edit configuration, write content, and troubleshoot problems without step-by-step guidance from you.
Any agent — install with npx:
npx skills add https://yasyf.github.io/cc-transcript/Codex / OpenCode
Tell the agent:
Fetch the skill file at https://yasyf.github.io/cc-transcript/skill.md and follow the instructions.Manual — download the skill file:
curl -O https://yasyf.github.io/cc-transcript/skill.mdOr browse the SKILL.md file.
SKILL.md
--- name: cc-transcript description: > Grep every Claude Code session you've ever run. Use when writing Python code that uses the cc_transcript package. license: PolyForm-Noncommercial-1.0.0 compatibility: Requires Python >=3.13. --- # cc-transcript Grep every Claude Code session you've ever run. ## Installation ```bash pip install cc-transcript ``` ## API overview ### Identity & digests Branded ids, the universal EventRef handle, and the cross-language tool digest. - `SessionId`: NewType creates simple unique types with almost zero runtime overhead - `EventUuid`: NewType creates simple unique types with almost zero runtime overhead - `ToolUseId`: NewType creates simple unique types with almost zero runtime overhead - `ToolDigest`: NewType creates simple unique types with almost zero runtime overhead - `EventRef`: A resolvable reference to a transcript event - `canonical_json`: Serialize ``value`` per RFC 8785 (JSON Canonicalization Scheme) - `tool_digest`: Digest a tool call's content into the cross-language join key ### Events & parsing The typed superset event model and the native parse entry points that produce it. - `parse`: Parses one transcript into a :class:`~cc_transcript.models.Transcript` view - `stream`: Streams parsed transcripts for ``paths`` off the native parse pool - `Transcript`: The parsed events of a single transcript file, backed by the native parse - `EventList`: A lazily-materializing sequence of transcript events over one parse output - `TranscriptEvent`: Represent a PEP 604 union type - `UserEvent`: A user turn - `AssistantEvent`: An assistant turn - `SystemEvent`: A system entry, such as a hook summary or notice - `SystemDetail`: Represent a PEP 604 union type - `StopHookSummary`: The typed detail of a ``stop_hook_summary`` system entry - `HookInfo`: One hook invocation recorded in a stop-hook summary - `CompactBoundary`: The typed detail of a ``compact_boundary`` system entry - `PreservedSegment`: The head/anchor/tail uuids of the segment preserved across a compaction - `PreservedMessages`: The message uuids preserved across a compaction - `TurnDuration`: The typed detail of a ``turn_duration`` system entry - `ModelRefusalFallback`: The typed detail of a ``model_refusal_fallback`` system entry - `OtherSystemDetail`: The catch-all detail for a system entry without a typed subtype - `ModeEvent`: A mode or permission-mode change marker - `OtherEvent`: Any recognized entry without a guaranteed conversational envelope - `AttachmentEvent`: A harness attachment record — a hook firing, a queued command, or an - `AttachmentDetail`: Represent a PEP 604 union type - `HookSuccess`: A hook that fired and exited cleanly, attached to the turn it ran on - `HookBlockingError`: A hook that blocked the turn, carrying the structured blocking payload - `HookNonBlockingError`: A hook that failed without blocking the turn - `HookCancelled`: A hook the harness cancelled, typically on timeout - `HookAdditionalContext`: Context a hook injected into the turn without blocking it - `AsyncHookResponse`: The result of an asynchronously-executed hook, matched back by process id - `QueuedCommand`: A user command queued for delivery to the agent, replayed as an attachment - `OtherAttachment`: Any attachment whose type has no typed detail, carried verbatim - `PrintMessage`: A conversational message lifted from a -p (print mode) result - `PrintResult`: A parsed 'claude -p --output-format json' result - `ContentBlock`: Represent a PEP 604 union type - `TextBlock`: A text content block from a user or assistant message - `ThinkingBlock`: An extended-thinking content block emitted by the assistant - `Question`: One AskUserQuestion round lifted from a tool-use input's ``questions`` array - `ToolUseBlock`: An assistant request to invoke a tool - `ToolResultBlock`: The result of a tool invocation, delivered in a user turn - `FallbackBlock`: A marker that the assistant turn fell back from one model to another - `OtherBlock`: Any assistant content block whose ``type`` is not yet modeled - `EntryMeta`: Envelope metadata shared by the conversational transcript events - `CcVersion`: NewType creates simple unique types with almost zero runtime overhead - `Usage`: Token usage and cache accounting for a single assistant turn or a -p (print mode) result - `ModelUsage`: Per-model token usage and cost from a -p (print mode) result's modelUsage map - `CacheCreation`: The split of cache-creation input tokens by TTL bucket - `ServerToolUse`: Server-side tool invocation counts billed within a turn - `Attribution`: The plugin, skill, or MCP tool an assistant turn is attributed to - `ApiError`: The upstream API error an assistant turn failed with - `McpServer`: An MCP server entry from the -p init element - `Plugin`: A plugin entry from the -p init element - `InitInfo`: The session init snapshot from a -p system/init element - `tool_uses`: The event's tool-use blocks, in content order - `thinking_chars`: The total character count of the event's extended-thinking blocks - `parse_event`: Parse one decoded transcript-line mapping into its typed event view - `parse_events`: Parse raw transcript-line mappings into typed native events - `parse_events_from_bytes`: Parse a JSONL transcript byte buffer into typed native events - `parse_print_result`: Parse a 'claude -p --output-format json' payload into a :class:`~cc_transcript.models.PrintResult` ### Synthetic transcripts Test-only builders that mint real native events by round-tripping envelope dicts through the parser. - `synthetic_user_event`: Builds a native :class:`~cc_transcript.models.UserEvent` from text or content blocks - `synthetic_assistant_event`: Builds a native :class:`~cc_transcript.models.AssistantEvent` from text or content blocks - `user_line`: A ``type: user`` envelope; ``blocks`` are ``message.content`` entries - `assistant_line`: An ``type: assistant`` envelope; ``blocks`` are ``message.content`` entries - `text_block`: A ``text`` content block carrying ``text`` - `thinking_block`: A ``thinking`` content block carrying ``thinking`` - `tool_use`: A ``tool_use`` content block invoking ``name`` with ``input`` under id ``id`` - `tool_result`: A ``tool_result`` content block for ``tool_use_id``; ``is_error`` marks a failed call - `meta_fields`: The envelope-level fields the parser lifts into :class:`~cc_transcript.models.EntryMeta` - `mode_line`: A ``mode``/``permission-mode`` envelope the parser lifts into :class:`~cc_transcript.models.ModeEvent` - `system_line`: A ``type: system`` envelope; ``fields`` carry the subtype-specific detail keys - `other_line`: An unmodeled-``type`` envelope lifted into :class:`~cc_transcript.models.OtherEvent`; ``raw`` is the line ### Cost Token pricing and the cost helper over assistant usage. - `ModelPricing`: USD-per-million-token rates for a model family - `CostBreakdown`: The per-component and total USD cost of a single turn's token usage - `cost_of`: Compute the USD cost of a turn's token usage under a model's rates - `cost_of_assistant`: Compute the cost of an assistant turn, or None when it carries no usage - `resolve_pricing`: Return the pricing row whose family key is a substring of `model` - `PRICING`: dict() -> new empty dictionary ### Tool calls One typed tool-call hierarchy shared by hook runtimes and the parser. - `ToolCall`: Represent a PEP 604 union type - `ToolCallBase`: Common shape of every typed tool call - `parse_tool_call`: Parse a tool's name and raw input into the typed hierarchy - `ToolInputError`: A known tool's input did not match its expected shape - `BashCall`: A Bash/Execute shell invocation - `ReadCall`: A Read of a file, optionally windowed - `WriteCall`: A Write/Create of a whole file - `EditCall`: An Edit replacement of ``old`` with ``new`` in one file - `MultiEditCall`: A MultiEdit applying ``edits`` to one file, in order - `NotebookEditCall`: A NotebookEdit replacing a cell's source - `GlobCall`: A Glob file-pattern search - `GrepCall`: A Grep content search - `ExitPlanModeCall`: An ExitPlanMode/ExitSpecMode plan submission - `SkillCall`: A Skill invocation - `TaskCall`: An Agent/Task subagent dispatch - `TaskCreateCall`: A TaskCreate tracker entry - `TaskUpdateCall`: A TaskUpdate tracker change - `WorkflowCall`: A Workflow dynamic-orchestration dispatch - `OtherCall`: A tool the platform does not type: unknown names, MCP tools, and — under - `EditSpan`: One replacement within a MultiEdit call, in application order - `Hunk`: A before/after content pair lowered from an edit-shaped tool call - `hunks_of`: Lower an edit-shaped call to before/after hunks; ``()`` for the rest - `file_path_of`: The file a call targets, when it targets one - `mcp_parts`: Split an ``mcp__server__tool`` name into ``(server, tool)``, else ``None`` - `mcp_access`: Classify an MCP tool segment as ``"read"`` or ``"write"`` by its verbs - `TOOL_ALIASES`: dict() -> new empty dictionary - `expand_tool_names`: Expand a pipe-separated tool spec to include alias and MCP bare spellings - `matches_names`: Whether ``actual`` is one of ``names``, exactly or as an MCP tool suffix - `tool_name_matches`: Whether ``actual`` matches a pipe spec, honoring aliases and MCP suffixes ### Tool results One typed per-tool result hierarchy over the record-level toolUseResult payload. - `ToolResult`: Represent a PEP 604 union type - `ToolResultBase`: Common shape of every typed tool result - `parse_tool_result`: Parse a tool's name and record-level ``toolUseResult`` into the typed hierarchy - `ToolResultError`: A known tool's result payload did not match its expected shape - `BashResult`: A Bash/Execute execution result - `EditResult`: An Edit result: the applied replacement and its structured patch - `WriteResult`: A Write/Create result: the written content and its structured patch - `ReadResult`: A Read result: the file payload and its content type - `TaskResult`: A completed Agent/Task subagent run - `TaskLaunchResult`: An in-flight Agent/Task launch (async or backgrounded subagent) - `SkillResult`: A Skill invocation result - `AskUserQuestionResult`: An AskUserQuestion result: the rounds, the answers, and any annotations - `QuestionAnnotation`: A reviewer's annotation on one answered AskUserQuestion round - `TextResult`: A plain-string tool result — denials and other unstructured payloads - `OtherResult`: A tool result the platform does not type: unknown tools, untyped tools ### Command lines Parsed bash command lines — the one command-parsing layer, tree-sitter-backed. - `Command`: A single parsed shell command with executable, arguments, env vars, and redirects - `CommandLine`: A full parsed bash command line, potentially containing multiple commands joined by operators - `CommandLineQuery`: Predicate helpers for inspecting a parsed ``CommandLine``. Obtain one via ``CommandLine.q`` - `Occurrence`: One command of a ``CommandLine`` with its position and joining context - `Redirect`: A shell redirect parsed from a bash command (e.g. ``> file.txt``, ``2>&1``) - `Word`: One structural word of a parsed command (``Command.words``) - `parse_command_line` - `command_prefixes`: Permission-style prefixes for each command of a shell command line ### Tool facts Flat per-tool-use facts lifted from session activity, with command-prefix and MCP roll-ups. - `ToolFact`: One tool call flattened for analytics, lifted from a parsed transcript - `tool_facts`: Yields one :class:`ToolFact` per tool call across every transcript file - `command_prefix_counts`: Counts every Bash command prefix across ``facts``, most frequent first - `mcp_summary`: Summarizes MCP usage per server across ``facts`` ### Session activity The spine — transcripts lifted into turns, tool uses, and first-class edits. - `SessionActivity`: A session's transcript lifted into turns, tool uses, and edits - `Turn`: One prompt-to-prompt span of a session - `ToolUse`: One tool invocation lifted from a turn's assistant events - `Edit`: A file modification lowered from an edit-shaped tool call - `UserClassifier` - `native_user_classifier`: Whether a user event is a real prompt under native Claude Code semantics - `hunk_overlap`: The fraction of ``a.new``'s non-empty lines present in ``b.old`` - `result_index`: Indexes tool results by the id of the tool use they answer ### Discovery & ingestion state Finding transcripts on disk and tracking what has been ingested. - `discover`: Every transcript under ``root``, sorted by path - `resolve`: Locates ``session_id``'s transcript on disk - `find_in`: Finds transcripts under ``directory`` newer than known mtimes - `subagent_paths`: Sidechain transcript files spawned by the session transcript at ``path`` - `TranscriptExpiredError`: A session's transcript file is gone from disk - `CLAUDE_PROJECTS_DIR`: Path subclass for non-Windows systems ### Codex sessions The OpenAI Codex CLI provider — rollout discovery, subagent joins, and per-rollout session info over the ~/.codex/sessions tree. - `CodexRollout`: A rollout found in the codex sessions tree - `CodexSessionInfo`: The identity, lifecycle, and usage of one codex rollout - `CodexUsage`: Session-level token totals lowered from a codex rollout - `CodexPendingItem`: A dangling tool call in the rollout's open turn - `codex.sessions_root` - `codex.discover` - `codex.find_transcript` - `codex.children_of` - `codex.session_info` ### Watch Live transcript tailing — byte-offset polling that yields each appended event exactly once. - `Watcher`: Tails every transcript under ``roots``, one :meth:`tick` per poll - `WatchEvent`: One transcript event freshly appended to a watched file ### Activity probe Disk-only session-activity verdicts over one transcript — captain-hook's is_waiting oracle, read straight from the file. - `activity_probe.SessionActivityProbe` - `activity_probe.session_activity_probe` ### Heartbeats Dispatch-heartbeat liveness records in the shared decisions.db ledger. - `heartbeats.HeartbeatLog` ### Notifications The harness notification-delivery queue, replayed from a session's events. - `Notifications`: The modeled state of a session's harness notification-delivery queue ### Filtering Filters-as-data — declarative specs and composable builders, executed in Rust at parse time or over materialized events. - `FilterSpec`: An ordered list of :class:`Clause` rules applied to an event stream - `filterspec.Clause` - `filterspec.spec_to_json` - `apply_spec`: Yields the already-materialized events that survive every ``DROP`` clause of ``spec`` - `annotate_spec`: Yields ``(event, labels)`` for events surviving ``spec``, with TAG labels, streaming lazily - `keep`: Returns whether ``event`` survives every ``DROP`` clause of ``spec`` - `labels_for`: Returns the TAG labels ``spec`` records for ``event``, in clause order - `build_spec`: Flattens ``Clause`` / ``tuple[Clause, ...]`` fragments into a :class:`FilterSpec` - `keep_only`: Drops every event whose kind is not in ``kinds`` - `drop_synthetic`: Drops assistant events with the ``<synthetic>`` model - `drop_empty`: Drops blank events of one kind - `drop_sidechain`: Drops sidechain events; ``except_assistants`` keeps assistant sidechains - `drop_meta_flag`: Drops events whose ``EntryMeta`` boolean ``flag`` is set - `drop_compacted`: Drops compaction-summary and transcript-only entries - `drop_entrypoints`: Drops events whose ``meta.entrypoint`` is in ``entrypoints`` - `drop_junk`: Drops events matching any group in the named :data:`JUNK_CATEGORIES` - `drop_phrases`: Drops events whose normalized text is one of ``phrases`` - `drop_short`: Drops events with at most ``max_words`` whitespace-split words - `NOISE_SPEC`: An ordered list of :class:`Clause` rules applied to an event stream - `filterspec.JUNK_CATEGORIES` - `USERS`: Build an immutable unordered collection of unique elements - `ASSISTANTS`: Build an immutable unordered collection of unique elements - `RESUME_PHRASE_SET`: Build an immutable unordered collection of unique elements - `TRIVIAL_ACK_SET`: Build an immutable unordered collection of unique elements - `STRUCTURAL_NOISE_RE`: Compiled regular expression object - `JUNK_USER_MESSAGE_RE`: Compiled regular expression object ### Context windows Refs-not-prose context — persisted EventRefs plus previews that hydrate back to full fidelity. - `ContextWindow`: The turns around an anchor event, persisted as refs plus previews - `HydratedWindow`: A context window resolved back to its real turns - `TurnRef`: A reference to one turn: resolvable refs plus a capture-time preview - `capture_window`: Capture the turns around ``anchor`` as a live, full-fidelity window - `SchemaError`: Persisted context data does not carry a known schema version ### Rendering The one renderer — budget-bounded turns, tool calls, and sessions; truncation happens only here. - `Budget`: Render-time character budgets — the only place the platform cuts content - `render_tool_call`: Render a typed tool call, clipping each content piece to the tool budget - `render_turn`: Render one turn: the prompt, assistant prose, and every tool call, in order - `render_session`: Render every turn of a session under ``budget``, separated by blank lines ### Evidence Incorrect-edit and correction harvest, with a read-only git pickaxe fallback. - `harvest_pairs`: Harvests incorrect-edit/correction pairs around ``anchor`` - `match_corrections`: Session corrections for ``edit``, ranked by overlap descending - `git_corrections`: Corrections to ``hunk`` found in ``repo``'s git history - `record_harvest`: Records ``pairs`` harvested around ``anchor`` into the shared ledger - `CandidatePair`: One incorrect-edit candidate and its best-matching correction - `GitFix`: A correction found in git history rather than the session ### Query The transcript query surface — sessions, tool-call queries, file refs, subagent recursion, and the recursive deep view. - `Session`: An immutable windowed view of a session's turns - `ToolCallQuery`: A chainable filter over a window's tool calls - `FileRef`: A file path carried by a tool call, with glob and prefix matching - `SubagentSession`: One Task dispatch joined to its sidechain transcript - `SubagentIndex`: The subagent dispatches of a session window - `DeepView`: The recursive union of a session and every transcript reachable from it - `DeepSession`: One transcript reached by :meth:`Session.walk` ### Decisions The unified decision ledger, joined to tool calls by content digest. - `DecisionLog`: The ``decisions`` ledger at ``~/.cc-transcript/decisions.db`` - `Decision`: One row of the decision ledger - `Action` - `DECISIONS_DDL`: str(object='') -> str ### Corrections The cross-language correction ledger — incorrect edits paired with the fix that later overwrote them, joined to tool calls by content digest. - `CorrectionLog`: The ``corrections`` ledger at ``~/.cc-transcript/corrections.db`` - `Correction`: One incorrect edit and the correction that overwrote it - `Origin` - `CORRECTIONS_DDL`: str(object='') -> str ### Disk truth Typed reader for cc-review's session-activity export. - `DiskTruth`: A session's disk-level activity exported from cc-review - `TreeTurn`: One Claude prompt-to-stop window bracketed by working-tree snapshots - `FileAttribution`: One file's attribution ranges within one review version - `AttributionRange`: An inclusive span of new-side diff lines attributed to one turn - `load_export`: Parse a ``cc-review export activity`` payload - `export_activity`: Export ``session_id``'s disk truth by shelling out to cc-review ### NLP The UDPipe-backed token substrate — typed tokens with form, lemma, POS, codepoint span, polarity, and negation. - `nlp.analyze` - `nlp.Token` ### Sentiment Conversation buckets and a composable score spec around any inference engine. - `sentiment.bucket_events` - `sentiment.ConversationEvent` - `sentiment.ConversationBucket` - `sentiment.ConversationBucketer` - `sentiment.BucketKey` - `sentiment.BucketIndex` - `sentiment.BUCKET_MINUTES` - `sentiment.extract_bucket_keys` - `sentiment.SentimentScore` - `sentiment.InferenceEngine` - `sentiment.FilteredEngine` - `sentiment.ScoreSpec` - `sentiment.ScoreStage` - `sentiment.build_score_spec` - `sentiment.flag_frustration` - `sentiment.clamp_positive` - `sentiment.clamp_resume` - `sentiment.demote_mild_irritation` - `sentiment.Lexicon` ### Mining Feedback detectors, confidence calibration, candidate filtering, and the feedback store. - `mining.MiningSignal` - `mining.CandidateSignal` - `mining.Confidence` - `mining.NOISE_FLOOR` - `mining.MiningSpec` - `mining.mine` - `mining.mining_spec_to_json` - `mining.DENIAL_PREFIX` - `mining.DENIAL_KIND_USER_REJECTED` - `mining.DENIAL_KIND_PERMISSION_RULE` - `mining.USER_SAID_MARKER` - `mining.USER_SAID_TRAILER` - `mining.ANSWERED_PREFIX` - `mining.ANSWERED_TRAILER` - `mining.SourceKind` - `mining.FeedbackCandidate` - `mining.DedupKey` - `mining.dedup_key` - `mining.ReviewComment` - `mining.ReviewFormat` - `mining.FeedbackStore` - `mining.StoreSchema` - `mining.TransactionConflictError` - `mining.Stats` - `mining.sample_windows` ### Judge LLM verdict passes over the mined corpus — structured judging, audits, and eval math. - `judge.VerdictLike` - `judge.run_verdicts` - `judge.sample_audit` - `judge.Metrics` - `judge.AuditEstimate` - `judge.exact_upper_bound` - `judge.GoldenRow` - `judge.golden_result` - `judge.flip_pairs` - `judge.structured_judge` - `judge.resolved_model` ## Resources - [Full documentation](https://yasyf.github.io/cc-transcript/) - [llms.txt](llms.txt) — Indexed API reference for LLMs - [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs - [Source code](https://github.com/yasyf/cc-transcript)