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

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. Emptying also happens only on a full run, so npx srcpack web leaves other bundles 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
  outfile: "~/Downloads/bundle.txt",   // custom output path
  index: true,                         // include index header (default)
  prompt: "./prompts/review.md"        // prepend from file (or inline text)
}

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.

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.

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, 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 --dry-run       # Preview without writing files
npx srcpack --emptyOutDir   # Empty output directory before writing
npx srcpack --no-emptyOutDir # Keep existing files in 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