PromptPack

简体中文

Turn repository files selected by your existing coding agent into a Markdown context package for another agent or the GPT Pro web app.

The agent understands the task and selects files; the tool reads the actual source code, packages it, verifies it, and calculates statistics. No model API, database, or local service is required.

Explore relevant code. Package context for the next agent.

Installation and usage

Bun 1.4.2 or later is required. Bun is used for the runtime, dependency installation, and tests.

bun install --frozen-lockfile
bun run dev setup --help

To install the prompt-pack command and its short alias pp locally:

bun run build
bun link
pp --help
pp export --repo /path/to/repo --manifest /path/to/context.json

Both commands use the same CLI and accept the same arguments. The agent skill is named prompt-pack; pp is a shell command alias, not a separate skill.

Set up the skill once for the agent that will explore repositories. After installing the commands, run pp setup from any directory. Setup writes a self-contained skill with absolute Bun and CLI paths. From a source checkout, the equivalent commands are:

# Codex, for the current user (the default)
bun run dev setup

# Claude Code, for one repository
bun run dev setup --agent claude --scope project --repo /path/to/repo

The user-level locations are ~/.agents/skills/prompt-pack for Codex and ~/.claude/skills/prompt-pack for Claude Code. Project scope uses the corresponding .agents/skills/prompt-pack or .claude/skills/prompt-pack directory under --repo. Use --agent codex|claude|all, --scope user|project, and --repo <directory>; defaults are codex, user, and the current directory. Existing skill files are preserved unless --force is supplied.

The installed skill embeds absolute paths to Bun and the installed source or built CLI. Keep the tool installation in place after setup. After upgrading or moving it, run pp setup --force with the same agent and scope options. Setup does not install a global command. After building, the equivalent direct form is bun dist/cli.js setup ....

Start a new task in the configured agent using ordinary language, for example:

Explore the login implementation and export the context needed to design retries for GPT Pro. Give me the Markdown file and its token count.

The skill is intended to trigger when relevant, but automatic triggering is not guaranteed. If it does not trigger, start a new session and explicitly invoke $prompt-pack in Codex or /prompt-pack in Claude Code, then describe the task. You can also provide the agent usage guide directly.

Run a complete export example with the current project:

bun run dev export \
  --repo . \
  --manifest examples/context.json \
  --out .prompt-pack/prompt.md \
  --max-tokens 60000

On success, .prompt-pack/prompt.md and .prompt-pack/prompt.report.json are produced. Copy the Markdown into the target conversation, or provide it to the target model as a file. The tool does not operate a browser automatically.

You can also run the built output directly:

bun run build
bun dist/cli.js export --repo /path/to/repo --manifest /path/to/context.json --out /path/to/prompt.md

--manifest - reads the JSON manifest from standard input. Omitting --out creates a unique run directory under the target repository: .prompt-pack/<unique-id>/context.json, prompt.md, and prompt.report.json. Each run includes its own .gitignore; the repository's existing ignore files are unchanged. The CLI prints the archived Manifest and Report paths, plus the Prompt path on success. This is useful for agent-generated manifests and avoids --force; use --force only when intentionally rerunning to the same explicit output path. With explicit --out, stdin manifests are not archived, and the destination/report behavior below applies.

For example:

printf '%s\n' '{"version":1,"task":{"goal":"Review login retries","deliverable":"Findings","constraints":[]},"handoff":{"findings":[],"hypotheses":[],"questions":[]},"files":[{"path":"src/login.ts","reason":"Retry entry point"}]}' \
  | bun run dev export --repo /path/to/repo --manifest -

Having an agent use it

The setup flow installs this guidance for Codex or Claude Code. For a manual fallback, provide the agent usage guide and tell the agent the project path and export tool path. For example:

Follow agent-usage.md to explore this repository and assemble the context needed to implement login retries. First select the entry point, implementation, callers, relevant tests, and necessary conventions; generate the selection list, then call prompt-pack to export it. Finally, give me the successful Markdown path and statistics.

The tool does not explore repositories or call models on its own. Do not ask the agent to copy source code into the list; it only needs to list file paths.

Manifest format

{
  "version": 1,
  "task": {
    "goal": "Analyze retry behavior after login failures",
    "deliverable": "A change plan, affected files, and testing suggestions",
    "constraints": ["Keep the public API compatible"]
  },
  "handoff": {
    "findings": [
      { "text": "The login entry point calls the shared client", "evidence": ["src/login.ts"] }
    ],
    "hypotheses": ["The failure may be related to the timeout policy and needs verification"],
    "questions": ["Which errors may be retried?"]
  },
  "files": [
    { "path": "src/login.ts", "reason": "Login entry point and error handling" }
  ]
}

• Required: version: 1, task.goal, task.deliverable, a non-empty files array, and path and reason for each file.
• constraints and handoff are optional; their default arrays are empty.
• File paths are relative to --repo and use / as the separator; CLI argument paths are relative to the current working directory.
• File names are processed literally. Names containing Chinese characters, spaces, or []*?{} are supported and are not expanded as globs.
• Evidence must cite files in the manifest; the tool does not verify whether the agent's textual conclusions are correct.
• Unknown fields, duplicate normalized paths, absolute paths, .., backslashes, control characters, and symbolic links are rejected. The first version supports only complete ordinary files, not line ranges.

Export behavior

The Markdown contains the task, handoff notes, selection reasons, a directory tree of selected files, and source code. Source code retains comments, blank lines, and leading and trailing whitespace; it is decoded using Repomix's text encoding detection without code compression. Source containing Markdown fences can be displayed in full.

Repomix's default ignore rules, .gitignore, .ignore, .repomixignore, and sensitive-content checks are reused. If an explicitly selected file is ignored, identified as binary, or flagged as sensitive content, the export fails and explains the reason in the report. The per-file limit is 50,000,000 bytes.

The target repository's Repomix JS/TS configuration is not loaded, and file processors are not executed. To exclude existing generated files as a whole, add the relevant directory to an ignore file in the target repository.

--max-tokens is optional. Statistics cover the final Markdown in full, using the fixed o200k_base encoding; per-file token counts cover only file bodies, so their sum is usually lower than the total. The budget is the upper limit set by the user; it does not represent the actual capacity of the target model or web app.

When the budget is exceeded, files are not truncated or removed automatically. A report is returned so the agent can adjust the selection. The report's fileTokens are sorted from largest to smallest by token usage.

Artifacts and exit codes

With explicit --out prompt.md, the destination corresponds to prompt.report.json; if there is no extension, .report.json is appended. Without --out, the run directory contains the archived input manifest as context.json, the Markdown as prompt.md, and its report. The report contains the status, file set, omission reasons, token statistics, budget, and runtime version; it does not contain source code or the original text of sensitive-content matches.

| Exit code | Meaning | Next step | | --- | --- | --- | | 0 | Success | Provide the promptPath from this run | | 1 | Runtime or write failure | Review the error, resolve it, and retry | | 2 | Manifest, path, or argument error | Correct the input; existing artifacts require explicit --force | | 3 | Incomplete selection | Review missingFiles / extraFiles and adjust the manifest | | 4 | Budget exceeded | Reduce the selection or explicitly increase the budget |

Existing Markdown or reports are not overwritten by default. Unique output directories avoid collisions; --force allows replacing artifacts at an explicitly reused output path, but cannot overwrite the manifest or selected source files, including path aliases and hard links.

The Markdown is published only after verification and budget checks pass. A failure caused by budget or missing files does not replace an old Markdown file; the report's promptPath is null, preventing an old result from being mistaken for this run's success. Each file is written atomically on its own; Markdown and the report are not a cross-file transaction, and a disk write failure is represented by a nonzero exit code. A pending report left after interruption does not indicate success.

Early errors such as argument parsing, manifest parsing, and output path conflicts are reported only on standard error to avoid writing to paths that have not been verified. Other failures write a JSON report where possible. Do not write concurrently to the same output path, and keep repository files unchanged during export.

Development

See CONTRIBUTING.md for development setup, validation, and pull request guidance.

Technology stack: Bun, TypeScript strict mode, Commander, Zod, Repomix, and Vitest. Dependencies are pinned; use bun.lock to reproduce the installation.

bun run typecheck
bun run test
bun run build

Tests use temporary directories and the real Repomix API, covering special file names, ignore rules, binary and sensitive-content filtering, budgets, retrying after failure, source protection, and the Bun CLI.

Future plans: line ranges, Git diffs, code-structure summaries, output splitting, and a local web interface that reuses the current export service. Internal design and planning live in the ignored docs/internal/ directory and are not committed.

Reference projects

• RepoPrompt CE: workflows for exploration results and context handoff.
• Repomix: an MIT-licensed file packaging tool whose public library interfaces this project reuses for searching, reading, sensitive-content checks, and token counting.

Releases

The first npm release is being prepared. Source installation above remains available. Once published, install with bun add -g @ultralitejs/prompt-pack, then run pp setup --agent codex or pp setup --agent claude.

Maintainers can run bun run release:check to build and validate a tarball locally, or bun run release to publish a committed version to npm and GitHub Releases. See the release guide for prerequisites and recovery. Use bun run release --skip-github to publish npm and the Git tag without GitHub CLI login, then create the GitHub Release in the browser. Releases run locally; no GitHub Actions workflow is required.