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.md

Or browse the SKILL.md file.

SKILL.md

---
name: cc-transcript
description: >
  Typed events for Claude Code transcripts: discovery, a superset JSONL parser (Python + Rust), and ingestion-state tracking. Use when writing Python code that uses the cc_transcript package.
license: PolyForm-Noncommercial-1.0.0
compatibility: Requires Python >=3.13.
---

# cc-transcript

Typed events for Claude Code transcripts: discovery, a superset JSONL parser (Python + Rust), and ingestion-state tracking.

## Installation

```bash
pip install cc-transcript
```

## API overview

### Classes

Core classes

- `TranscriptDiscovery`: Locates Claude Code transcript files on disk
- `TranscriptParser`: The public facade over the active parsing backend
- `FileStateStore`: Tracks which transcript files have been ingested, keyed by mtime
- `rust.RustBackend`
- `parser.PythonBackend`
- `sentiment.NLP`
- `sentiment.ConversationBucketer`
- `sentiment.Lexicon`

### FileStateStore Methods

Methods for the FileStateStore class

- `FileStateStore.open`
- `FileStateStore.close`
- `FileStateStore.__aenter__`
- `FileStateStore.__aexit__`
- `FileStateStore.transaction`
- `FileStateStore.file_mtimes`
- `FileStateStore.record_file`
- `FileStateStore.upsert_file`

### Dataclasses

Data-holding classes

- `ParsedTranscript`: The parsed events of a single transcript file
- `FilterConfig`: Opt-in, consumer-side filtering of a transcript event stream
- `FilterSpec`: An ordered list of :class:`Clause` rules applied to an event stream
- `AssistantEvent`: An assistant turn
- `EntryMeta`: Envelope metadata shared by the conversational transcript events
- `ModeEvent`: A mode or permission-mode change marker
- `OtherEvent`: Any recognized entry without a guaranteed conversational envelope
- `SystemEvent`: A system entry, such as a hook summary or notice
- `TextBlock`: A text content block from a user or assistant message
- `ThinkingBlock`: An extended-thinking content block emitted by the assistant
- `ToolResultBlock`: The result of a tool invocation, delivered in a user turn
- `ToolUseBlock`: An assistant request to invoke a tool
- `UserEvent`: A user turn
- `filterspec.KindIs`
- `filterspec.MetaFlag`
- `filterspec.EntrypointIn`
- `filterspec.ModelIs`
- `filterspec.TextEmpty`
- `filterspec.TextMatchesAny`
- `filterspec.TextInSet`
- `filterspec.WordCountAtMost`
- `filterspec.Clause`
- `builders.Clause`
- `builders.EntrypointIn`
- `builders.KindIs`
- `builders.MetaFlag`
- `builders.ModelIs`
- `builders.TextEmpty`
- `builders.TextInSet`
- `builders.TextMatchesAny`
- `builders.WordCountAtMost`
- `filters.Clause`
- `filters.EntrypointIn`
- `filters.KindIs`
- `filters.MetaFlag`
- `filters.ModelIs`
- `filters.TextEmpty`
- `filters.TextMatchesAny`
- `sentiment.FilteredEngine`
- `sentiment.FrustrationShortCircuit`
- `sentiment.MildIrritationDemote`
- `sentiment.PositiveClamp`
- `sentiment.ResumeClamp`
- `sentiment.ScoreSpec`

### Protocols

Structural typing protocols

- `Backend`: A transcript-parsing backend
- `sentiment.InferenceEngine`

### Enumerations

Enum types

- `filterspec.Action`

### Named Tuples

NamedTuple types

- `AssistantMessage`: An assistant turn distilled for analysis: its text, tool calls, and responding model
- `ToolCall`: A single tool invocation within a message: the tool ``name`` and optional target file path
- `UserMessage`: A user turn distilled for analysis: its text, tool calls, and authoring metadata
- `sentiment.BucketKey`
- `sentiment.ConversationBucket`

### Functions

Public functions

- `build_spec`: Flattens ``Clause`` / ``tuple[Clause, ...]`` fragments into a :class:`FilterSpec`
- `drop_compacted`: Drops compaction-summary and transcript-only entries
- `drop_empty`: Drops blank events of one kind
- `drop_entrypoints`: Drops events whose ``meta.entrypoint`` is in ``entrypoints``
- `drop_junk`: Drops events matching any group in the named :data:`JUNK_CATEGORIES`
- `drop_meta_flag`: Drops events whose ``EntryMeta`` boolean ``flag`` is set
- `drop_phrases`: Drops events whose normalized text is one of ``phrases``
- `drop_short`: Drops events with at most ``max_words`` whitespace-split words
- `drop_sidechain`: Drops sidechain events; ``except_assistants`` keeps assistant sidechains
- `drop_synthetic`: Drops assistant events with the ``<synthetic>`` model
- `keep_only`: Drops every event whose kind is not in ``kinds``
- `apply_filters`: Yields the events that survive ``config``
- `annotate_spec`: Yields ``(event, labels)`` for events surviving ``spec``, with TAG labels
- `apply_spec`: Yields the events that survive every ``DROP`` clause of ``spec``
- `keep`: Returns whether ``event`` survives every ``DROP`` clause of ``spec``
- `labels_for`: Returns the TAG labels ``spec`` records for ``event``, in clause order
- `parse_event`
- `parse_events_from_bytes`
- `rust.is_portable`
- `rust.spec_to_json`
- `parser.parse_meta`
- `parser.flatten_result_content`
- `parser.parse_user_blocks`
- `parser.parse_assistant_blocks`
- `parser.parse_assistant_block`
- `parser.decode_line`
- `parser.parse_one`
- `parser.parse_one_filtered`
- `parser.load_rust_backend`
- `filterspec.compile_groups`
- `filterspec.event_kind`
- `filterspec.event_text`
- `filterspec.event_meta`
- `filterspec.normalize_bare`
- `filterspec.predicate_matches`
- `filterspec.meta_flag`
- `filterspec.clause_matches`
- `filterspec.is_portable`
- `filterspec.clause_portable`
- `filterspec.spec_to_json`
- `filterspec.clause_to_dict`
- `filterspec.predicate_to_dict`
- `filters.compile_groups`
- `sentiment.NOOP_PROGRESS`
- `sentiment.build_score_spec`
- `sentiment.clamp_positive`
- `sentiment.clamp_resume`
- `sentiment.demote_mild_irritation`
- `sentiment.extract_bucket_keys`
- `sentiment.flag_frustration`

### Async Functions

Asynchronous functions

- `parse_events_async`

### Constants

Module-level constants and data

- `CcVersion`: NewType creates simple unique types with almost zero runtime overhead
- `EntryUuid`: NewType creates simple unique types with almost zero runtime overhead
- `SessionId`: NewType creates simple unique types with almost zero runtime overhead
- `ToolUseId`: NewType creates simple unique types with almost zero runtime overhead
- `parser.ContentBlock`
- `parser.TranscriptEvent`
- `parser.INTERRUPT_MARKER`
- `parser.build_event`
- `models.ContentBlock`
- `models.TranscriptEvent`
- `filterspec.TranscriptEvent`
- `filterspec.EventKind`
- `filterspec.MetaFlagName`
- `filterspec.TRAILING_PUNCT`
- `filterspec.STRUCTURAL_TAG_GROUP`
- `filterspec.STRUCTURAL_GROUPS`
- `filterspec.AGENT_INJECTION_GROUPS`
- `filterspec.INTERRUPT_MARKER_GROUPS`
- `filterspec.STOP_HOOK_GROUPS`
- `filterspec.CONTINUATION_GROUPS`
- `filterspec.COMMAND_ECHO_GROUPS`
- `filterspec.JUNK_CATEGORIES`
- `filterspec.STRUCTURAL_NOISE_GROUPS`
- `filterspec.SENTIMENT_JUNK_GROUPS`
- `filterspec.FRUSTRATION_GROUPS`
- `filterspec.MILD_IMPATIENCE_GROUPS`
- `filterspec.PORTABLE_GROUP_NAMES`
- `filterspec.RESUME_PHRASE_SET`
- `filterspec.TRIVIAL_ACK_SET`
- `filterspec.SHORT_MESSAGE_MAX_WORDS`
- `filterspec.CONVERSATIONAL`
- `filterspec.USERS`
- `filterspec.ASSISTANTS`
- `filterspec.Predicate`
- `filterspec.STRUCTURAL_NOISE_RE`
- `filterspec.INTERRUPT_MARKER_RE`
- `filterspec.STOP_HOOK_RE`
- `backend.TranscriptEvent`
- `builders.ASSISTANTS`
- `builders.JUNK_CATEGORIES`
- `builders.USERS`
- `builders.EventKind`
- `builders.MetaFlagName`
- `builders.NOISE_SPEC`
- `store.FILE_SCHEMA`
- `discovery.CLAUDE_PROJECTS_DIR`
- `filters.ASSISTANTS`
- `filters.SENTIMENT_JUNK_GROUPS`
- `filters.USERS`
- `filters.EventKind`
- `filters.TranscriptEvent`
- `filters.JUNK_USER_MESSAGE_RE`
- `filters.KIND_BY_TYPE`
- `messages.BaseMessage`
- `messages.TranscriptMessage`
- `sentiment.BUCKET_MINUTES`
- `sentiment.MIN_USER_CHARS`
- `sentiment.MIN_USER_TURNS_PER_SESSION`
- `sentiment.BaseMessage`
- `sentiment.BucketIndex`
- `sentiment.ScoreStage`
- `sentiment.SentimentScore`
- `sentiment.TranscriptMessage`

### Other

Additional exports

- `domains`

## 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)