Srcpack

Zero-config CLI for bundling code into LLM-optimized context files.

Requirements: Node.js 22.18+ or Bun

Quick Start

npx srcpack init         # Create config interactively
npx srcpack              # Bundle all except on-demand

Why

LLM context fails when codebases are large, noisy, or poorly organized. Srcpack lets you split code into semantic bundles (e.g., web, api, docs) with clear file boundaries and an index header—optimized for ChatGPT, Claude, Gemini, etc.

Configuration

Create srcpack.config.ts in your project root (use srcpack.config.mts if your package.json lacks "type": "module" — srcpack init picks the right one):

import { defineConfig } from "srcpack";

export default defineConfig({
  bundles: {
    web: "apps/web/**/*",
    api: ["apps/api/**/*", "!apps/api/**/*.test.ts"],
    docs: {
      include: "docs/**/*",
      index: false, // disable index header
    },
  },
});

Or add to package.json:

{
  "srcpack": {
    "bundles": {
      "web": "apps/web/**/*"
    }
  }
}

Options

| Option | Default | Description | | ------------- | ---------- | ------------------------------------- | | outDir | .srcpack | Output directory for bundles | | emptyOutDir | true* | Empty output directory before writing | | bundles | — | Named bundle definitions | | upload | — | Upload destination(s) |

*Only the default .srcpack is emptied automatically — it's srcpack's directory by convention. Any other outDir needs an explicit emptyOutDir: true, so outDir: "src" can't quietly delete your sources. Named runs (npx srcpack web) never empty it, so other bundles stay in place.

Bundle Config

// Simple glob
"src/**/*"

// Array with exclusions (! prefix)
["src/**/*", "!src/**/*.test.ts"]

// Force-include gitignored files (+ prefix)
["docs/**/*", "+docs/**/*.local.md"]

// Changed files instead of a glob (git: prefix)
["git:staged", "!bun.lock"]

// Full options
{
  include: "src/**/*",
  linear: { team: "ENG" },             // Linear issues as virtual files
  screenshot: "http://localhost:5173", // rendered page as numbered PNGs
  outfile: "~/Downloads/bundle.txt",   // custom output path
  index: true,                         // include index header (default)
  prompt: "./prompts/review.md",       // prepend from file (or inline text)
  onDemand: true                       // build only when named
}

Patterns follow glob syntax. Prefix with ! to exclude, + to force-include (bypasses .gitignore). Binary files are excluded.

A pattern can also name a set of changed files: git:staged, git:unstaged, git:untracked, git:dirty, or git:<rev> (e.g. git:main, git:HEAD~3). Deleted files are skipped, and git:<rev> compares against the merge base so a stale branch still reports only your own changes. See Git sources.

A full run skips bundles marked onDemand: true; name them explicitly to build them. Emptying outDir still removes their previous output there. See On-Demand Bundles.

Linear Issues

A bundle can include Linear issues next to your code. Each issue becomes a virtual file at linear/issues/ENG-123.md, so it gets its own index entry and line range — letting you ask whether [4] src/board.ts actually implements [2] ENG-123.

bundles: {
  backlog: { linear: "ENG" },                       // non-terminal issues, team ENG
  planning: {
    include: ["docs/**/*.md"],
    linear: { team: "ENG", project: "Roadmap" },    // scoped to one project
  },
}

Authentication reads LINEAR_API_KEY from the environment (Linear → Settings → Security & access → Personal API keys), never from the config file. team is required, completed/canceled/duplicate issues are excluded by default, and issues obey ! exclusions like any other entry. See Linear issues.

Screenshots

A bundle can capture a rendered page as PNGs, with overlapping detail slices for tall pages. Srcpack scrolls to load lazy content before capture and hides Astro and Nuxt dev toolbars.

bundles: {
  home: { screenshot: "http://localhost:5173/", onDemand: true },
}

npx srcpack home writes PNGs to .srcpack: home-00.png is the whole page when available; tall pages also get home-01.png, home-02.png, … detail slices. Attach them in filename order. Images stay local, even with upload configured. For a one-off, no config is needed: npx srcpack --screenshot localhost:5173 --viewport mobile. See Screenshots for Playwright and browser setup.

Google Drive Upload

To upload bundles to Google Drive, add OAuth credentials to your config:

export default defineConfig({
  bundles: {/* ... */},
  upload: {
    provider: "gdrive",
    folderId: "1ABC...", // Google Drive folder ID (from URL)
    clientId: "...",
    clientSecret: "...",
    exclude: ["local"], // skip specific bundles
  },
});

Setup:

1. Go to Google Cloud Console
2. Create a project (or select existing)
3. Enable the Google Drive API
4. Go to Credentials → Create Credentials → OAuth client ID
5. Select Desktop app, then copy the client ID and secret
6. Run npx srcpack login to authenticate

Output Format

# Index (3 files)
# [1]   src/api.ts  L7-L67 (61 lines)
# [2]   src/index.ts  L69-L110 (42 lines)
# [3]   src/utils.ts  L112-L158 (47 lines)

#==> [1] src/api.ts <==
export async function fetchBoard() {
...

#==> [2] src/index.ts <==
import { utils } from "./utils";
...

• Numbered entries for easy cross-reference in conversations
• Line ranges point to actual content lines
• # prefix keeps format safe inside code blocks

CLI

npx srcpack                 # Bundle all except on-demand, upload if configured
npx srcpack web api         # Bundle specific bundles only
npx srcpack --staged        # Bundle staged changes (no config needed)
npx srcpack --dirty         # Bundle staged + unstaged + untracked
npx srcpack --since main    # Bundle changes since main
npx srcpack --screenshot localhost:5173 # Capture a page as PNGs
npx srcpack --dry-run       # Preview without writing files
npx srcpack --emptyOutDir   # Empty output directory before writing
npx srcpack --no-emptyOutDir # Skip clearing the output directory
npx srcpack --no-upload     # Bundle only, skip upload
npx srcpack init            # Interactive config setup
npx srcpack login           # Authenticate with Google Drive

API

import { defineConfig, loadConfig } from "srcpack";

// In config files
export default defineConfig({
  bundles: { web: "apps/web/**/*" },
});

// Programmatic
const config = await loadConfig();

LLM Context

• https://kriasoft.com/srcpack/llms.txt
• https://kriasoft.com/srcpack/llms-full.txt

Community

• Discord — Questions, feedback, and discussion
• GitHub Issues — Bug reports and feature requests

New contributors and OSS maintainers are welcome — join us on Discord or open an issue / PR.

Backers

License

MIT