Quick Clipboard

Quick Clipboard is a VS Code extension for turning files and folders into LLM-ready project context. It can copy a Markdown payload, copy only the project structure, or write self-contained Markdown and PDF artifacts that are ready to drag into an AI chat.

The main workflow is provider-independent: it does not require Claude, an API key, a network connection, or any particular chat application. Paste the copied Markdown into ChatGPT, Gemini, a local model, a web chat, or any other tool that accepts text.

An optional Claude Code command can stage a packed folder through an @file reference. That integration is an extra adapter, not a dependency of copying, bundling, safety checks, file discovery, or local token reporting.

Install

Install Quick Clipboard from the Visual Studio Marketplace, or search for Quick Clipboard in VS Code's Extensions view and choose the extension published by alfie-ns.

The equivalent command-line installation is:

code --install-extension alfie-ns.quick-clipboard

Repository collaborators can also install a packaged .vsix from GitHub Releases. From a local checkout, ./release.sh --package-only builds one under release/ without changing the version, committing, tagging, or publishing. Reload or restart VS Code after installation. F5 is only used when developing the extension itself.

Copy project context

1. Open a trusted project in VS Code.
2. In the Explorer sidebar, select a file, several files, or a directory.
3. Right-click the selection.
4. Choose Copy as LLM Context.

Quick Clipboard then:

1. Finds the eligible text files inside the selection.
2. Applies ignore rules and safety exclusions.
3. Builds a project architecture tree.
4. Adds each file's contents in a path-labelled Markdown fence.
5. Copies the complete payload to the clipboard.

That is the whole click. Nothing stands between the click and the copy: no dialog, no confirmation, no network call. Token counting runs afterwards, off the extension-host thread, and lands in the status bar as a compact receipt containing the token count, character count, and file count. Select it for the file-by-file breakdown, largest first.

The receipt leads with delivery, for example 12 files copied · 18.4k tok, and its tooltip records how many Explorer selections expanded into those files. A folder still counts as one selection even when it contributes many descendants; the clipboard receives one combined Markdown payload.

Optional double-tap compaction

After a successful copy, run Copy as LLM Context a second time within 400 ms to replace that same owned clipboard payload with a signatures-first compact version. The first copy is always the complete context. The second gesture:

• reuses the already packed files and never scans the workspace again;
• keeps the architecture, imports, declarations, headings, and explicit omitted-line markers;
• verifies the current text clipboard by byte length and SHA-256 before replacing it;
• cancels if another application changed the clipboard or ownership cannot be verified; and
• ignores invocations closer than 150 ms so holding the shortcut cannot forge a double-tap.

The teaching hint remains visible briefly, but the replacement window itself is only 400 ms. No background task changes the clipboard automatically.

Attach PDFs, images, and other binary files

Copy as LLM Context always puts eligible text on the clipboard first. When the same selection also contains PDFs, images, or other files that cannot be safely inlined as text, Quick Clipboard can copy those files verbatim into a temporary bundle folder and open it for dragging into the destination chat.

• Attachment staging is enabled by default, but the first use in each workspace asks before writing the files.
• Declining the prompt leaves the already-copied text untouched.
• Per-file, total-size, file-count, and storage limits prevent an accidental unbounded copy. Every excluded or failed attachment is named in the receipt.
• The flow works only where the extension host can open a local file manager. In remote and web workspaces, the text is still copied and the unavailable attachments are reported.
• Temporary attachment bundles are retained long enough to drag from and are reaped on a later activation according to quickClipboard.stagedContextTtlHours and the storage budget.

Set quickClipboard.attachments.enabled to false if you want the original text-only behavior.

Build a self-contained AI bundle

Choose Bundle for AI (one file) from the Explorer context menu, or run it from the Command Palette to use the whole open workspace. The command writes persistent artifacts under .llm/ by default and reveals the primary artifact in the VS Code Explorer.

The default produces both:

• context.md, the lossless UTF-8 architecture and source-text record; and
• context.pdf, a citable document with line-numbered source, supported images, and real pages spliced from source PDFs.

Each format is usable on its own; set quickClipboard.bundle.formats to md or pdf if you want exactly one output. When the PDF cannot represent a file faithfully, it says so and points to context.md or the original file instead of silently replacing characters or inventing content. Generated bundle directories exclude themselves from the next discovery pass.

After writing, Quick Clipboard can make an advisory check for the companion Drop Bridge extension. A failed check never blocks the bundle; it warns that dragging from VS Code into a browser may deliver a path string, in which case you can drag from the operating-system file manager instead.

Optional: send a folder to Claude Code

Skip this section if you do not use Claude Code. Nothing in the normal copy workflow calls Claude or Anthropic.

1. Start Claude Code in a VS Code integrated terminal:

   claude
   

2. In the Explorer sidebar, right-click the directory to provide as context.

3. Choose Stage in Claude Code Terminal.

4. Review the payload breakdown.

5. Choose the running Claude terminal if VS Code cannot identify it unambiguously.

Quick Clipboard writes the packed payload to a unique private file and inserts only an absolute reference into Claude's prompt:

@"/absolute/path/to/main-prompt-context.md"

It does not press Enter. Type the actual request after the reference, then submit it yourself. This keeps large payloads out of the terminal input buffer and preserves a chance to edit the request before Claude reads the staged file.

Claude directory references normally provide a directory listing. Quick Clipboard instead references one generated Markdown file containing both the architecture and the selected file contents.

Payload format

The copied or staged document has this shape:

# Project context

## Architecture

```text
.
├── package.json
└── src/
    └── extension.ts
```

## File contents

### File: package.json

```json
...
```

Markdown fences automatically grow longer when a source file already contains runs of backticks.

File discovery and ignore rules

Inside a Git repository, Quick Clipboard uses:

git ls-files --cached --others --exclude-standard -z

This includes tracked files and untracked files that are not ignored by repository, information-exclude, or global Git rules. Git is invoked without a shell, and paths are read as NUL-delimited values. A Git failure stops the operation instead of silently switching to weaker ignore behaviour.

Outside a Git repository, a streaming recursive walker applies directory-scoped .gitignore rules. It checks cancellation between entries and does not follow symlinks.

An explicitly selected individual file can override ordinary ignore rules. Secret exclusions can never be overridden.

Safety behaviour

Quick Clipboard hard-blocks common secret-bearing paths before reading them, including:

• .env and .env.*
• private keys, keystores, and Terraform state
• Git, npm, Python, Docker, Kubernetes, AWS, and cloud credential files
• credential, service-account, secret, and authentication JSON files

It also scans allowed text for high-confidence private-key and API-token shapes. Potential content matches never delay the copy: the flagged files are copied with everything else, and a notice arrives alongside the copy naming them, with a one-click re-copy that strips them. Hard-blocked files remain excluded, always.

Additional safeguards:

• Directory discovery does not follow symlinks, and explicitly supplied file symlinks are skipped. Canonical paths are rechecked for selection containment and secret rules before any file is read.
• FIFOs, sockets, devices, and other non-regular files are skipped.
• NUL-containing, binary, malformed UTF-8, and control-heavy files are never inlined as text. With attachment staging enabled, they are carried verbatim subject to its limits; otherwise they are omitted and reported.
• Files that exceed the inline text limit are never silently truncated. They become attachments when enabled and within the attachment limits; otherwise they are omitted whole and reported.
• Folder-discovered lockfiles are excluded by default and shown in the report.
• Explicitly selected lockfiles are copied and then flagged in the notice, because they can dominate the token budget.
• Unsaved VS Code editor text replaces stale disk contents and is marked in the report.
• The clipboard is written the moment packing and exclusions complete; counting and notices trail it. Staged-file writes for the terminal remain review-first.

Clipboard managers and cloud clipboard synchronisation can retain copied source independently of this extension.

Token reporting

The default local tokeniser is o200k_base. cl100k_base is also available. Exact tokenisation runs in a worker so the VS Code extension host remains responsive.

The report contains:

• Unicode character count
• UTF-8 payload size
• included file count
• exact whole-payload count for the selected local tokeniser
• independently counted file blocks ranked by token weight
• architecture and framing boundary delta
• grouped omission reasons

These figures describe the generated payload. They do not include an LLM's existing conversation, system instructions, output, cache pricing, or subscription rules.

All counting is local. There is no networked counting mode: no payload, file, or count ever leaves the machine.

Commands

The normal workflow uses the Explorer right-click menu. Shift+Caps Lock is an optional shortcut for packing the file in the active editor. Shift+Alt+Caps Lock builds an AI bundle while the Explorer has focus. Explorer directory and multi-selection operations remain available from the context menu.

Only Copy as LLM Context is needed for normal use. The Claude-specific commands can be ignored completely.

Settings

Staged-file lifecycle

Staged payloads use unique immutable filenames under VS Code's workspace-specific extension storage. Permissions are restricted to 0600 where supported. A private operating-system temp directory is used only when workspace storage cannot provide a safe filesystem path.

Files are not removed when the extension deactivates because an unsubmitted Claude prompt may still reference one. Expired files are pruned on a later activation, and the clear command removes them immediately.

Development

Install the locked dependencies and run the test suite:

npm ci
npm test

To run an Extension Development Host, open the project in VS Code and press F5.

Release

The repository remembers the release procedure. For a safe local dry run that tests the extension and creates an installable VSIX without changing its version or publishing anything:

./release.sh --package-only

For a production release, run one command:

./release.sh

It verifies a clean main branch, installs the locked dependencies, runs all tests, increments the patch version, builds the VSIX, asks for confirmation, creates the release commit and tag, and pushes both. The tag triggers GitHub Actions, which attaches the tested VSIX to a GitHub Release. Use ./release.sh --bump minor or ./release.sh --bump major only when the release warrants it.

The public installation channel is the Visual Studio Marketplace. While the GitHub repository remains private, its Releases and .vsix assets are available only to repository collaborators.

Licence

Quick Clipboard is MIT-licensed. Packaged third-party software and font attributions are recorded in THIRD_PARTY_NOTICES.md.