CtxPack Akira Taniwaki

ai ai-agents cli context markdown tokens

Use this command to install CtxPack:

winget install --id=atani.ctxpack -e

CtxPack turns noisy web pages, HTML, or Markdown into compact context that AI agents can safely consume while tracking token savings.

CtxPack

日本語

Token-aware context extraction for AI agents.

CtxPack turns noisy web pages, HTML, or Markdown into compact context that agents can safely consume. It removes obvious page chrome, preserves useful structure, and tracks cumulative token savings over time.

ctxpack https://example.com/article
ctxpack https://example.com/article --query "pricing and limits" --json
ctxpack stats
ctxpack reset --yes

Why

AI agents often waste context on navigation, scripts, styles, cookie banners, footers, related links, and repeated boilerplate. Existing web-to-markdown tools are useful, but agents need one more step: token-aware packing with measurable savings.

CtxPack is designed as a tool an agent can call before reading a URL.

URL / HTML / Markdown
  -&gt; clean page chrome
  -&gt; extract readable text
  -&gt; move task-relevant sections toward the top
  -&gt; return compact Markdown or structured JSON
  -&gt; record how many tokens were saved

Example

ctxpack https://example.com/docs --stats

Markdown output includes source metadata and optional per-run savings:

Raw input:   42,100 tokens
Clean text:   7,800 tokens
Final:        7,800 tokens
Saved:       34,300 tokens
Reduction:   81.5%

For agents, use JSON:

ctxpack https://example.com/docs --json

{
  "ok": true,
  "source": { "url": "https://example.com/docs", "fetched_at": "..." },
  "title": "Example Docs",
  "content": { "format": "markdown", "text": "..." },
  "stats": {
    "raw_html_tokens": 42100,
    "clean_text_tokens": 7800,
    "final_tokens": 7800,
    "saved_tokens": 34300,
    "reduction_percent": 81.5
  }
}

Cumulative savings

Every normal run is recorded locally in ~/.ctxpack/stats.jsonl.

ctxpack stats

Runs:        24
Raw input:   1,024,000 tokens
Clean text:    181,200 tokens
Final:         181,200 tokens
Saved:         842,800 tokens
Reduction:     82.3%

Reset the history:

ctxpack reset --yes

Skip recording one run:

ctxpack https://example.com --no-record

Install

Homebrew

brew install atani/tap/ctxpack

Windows / winget

winget install atani.ctxpack

Releases ship Windows x64/arm64 ZIP artifacts and generated winget manifests. See packaging/winget/ for the submission flow and the automated update job.

From source

git clone https://github.com/atani/ctxpack.git
cd ctxpack
go install ./cmd/ctxpack

Or run during development:

go run ./cmd/ctxpack https://example.com --stats

Migrating from the Python version

ctxpack v0.2.x and earlier was a Python package. The CLI surface (flags, subcommands, exit codes, JSON schema) and the ~/.ctxpack/stats.jsonl history format are unchanged, so existing scripts and history keep working. The Python library API (from ctxpack import pack) is gone; if you installed via pip/uv tool install, switch to one of the install methods above.

CLI

ctxpack SOURCE [--query TEXT] [--json] [--stats] [--no-record] [-o FILE]
ctxpack run SOURCE [--query TEXT] [--json] [--stats] [--no-record] [-o FILE]
ctxpack stats [--json] [--reset]
ctxpack reset --yes

SOURCE can be:

https://... or http://...
a local HTML/Markdown file
- for stdin

Options:

--query TEXT — move task-relevant sections toward the top.
--json — structured output for agent tool calls.
--stats — include the per-run token savings table in Markdown output. JSON output always includes stats, so this flag only affects Markdown.
--no-record — do not add this run to cumulative savings.
-o FILE — write output to a file.

Exit codes:

0 — success.
1 — runtime error such as a network failure or an oversized response (often retriable).
2 — usage error or missing input file (not retriable).
3 — the fetched page appears to require JavaScript rendering (not retriable with ctxpack alone; see JavaScript-rendered pages).

How it works

Content filtering

CtxPack removes, before extracting text: