ekornhq/ekorn ↗★ 0

dsh-ekorn

ekorn for DeepSeek Harness. Saves tokens three ways: large tool results are stored on your machine and the model sees an exact summary it can fetch back line by line; long sessions are compacted when the model's cache prices say it pays off; long logs are read by a sub-agent on the cheaper model.

パッケージ
dsh-ekorn
互換性
未検証
バージョン
0.3.0
ライセンス
MIT
最終更新
2026/11/11

インストール

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:ekornhq/ekorn

ドキュメント

README 全文を読む ↗

ekorn

A token-saving toolkit for coding agents.

An agent re-sends its whole conversation with every request, so anything that enters the context is paid for again on every later turn. ekorn cuts that cost in four ways: it keeps large output out of the context (stored on your machine, fetched back exactly when needed), removes avoidable round trips, compacts the conversation at the right time, and measures the result so its settings can be tuned from evidence. It runs through the agent's hooks, so there is nothing to remember to do.

ekorn 是给编码代理用的省 token 工具集。代理每次请求都会把整段对话重发一遍, 进了上下文的内容之后每一轮都要再付一次。ekorn 从四处省:大输出不进上下文 (原样存本机,需要时逐行取回)、减少多余的模型往返、在合适的时机压缩对话、 用本机账本量出效果并据此调参。全部通过钩子自动生效,你的数据不出你的机器。

Works with Claude Code, Codex CLI and DeepSeek Harness. Claude Code gets all of it; the table below shows the rest.

How it saves tokens

1. Large output stays out of the context

A hook wraps shell commands that tend to print a lot. Output over 16 KiB is archived verbatim and the model sees an exact summary instead. A 30,000-line output becomes this (summary text is currently in Chinese):

[ekorn-pack] shell 输出 168893 字节 / 30000 行,已归档,上下文只保留摘要
id: obs_57ed597060d172dd
path: ~/.ekorn/store//obj/obs_57ed597060d172dd.txt
recall: ekorn recall obs_57ed597060d172dd --offset 0            # 按字节精确翻页
grep:   ekorn recall obs_57ed597060d172dd --grep 'PATTERN'      # 只取命中行(带行号)
--- 头 60 行 ---
…
--- 中间省略 29915 行 / 168573 字节 ---
--- 尾 25 行 ---
…

and the model gets any part back, byte for byte, when it needs it:

$ ekorn recall obs_57ed597060d172dd --lines 29999-29999
[ekorn-recall id=obs_57ed597060d172dd lines=29999-29999 of 168893 bytes]
  29999: 29999

Two more things keep large content out:

  • File reads are capped. A read of a large file with no range is limited, so the model pages through the part it needs instead of loading the whole file.
  • Long logs go to a sub-agent. The log-reducer agent reads a long log in its own context and brings back only the lines that matter, each one checked word for word against the source by ekorn verify.

2. Fewer round trips

  • Edit and check in one call. The MCP tools edit_then_run and write_then_run change a file and run your build or test in the same tool call, instead of an edit, a reply, and then a separate command.
  • Four rules at session start. A hook gives the model a short discipline: combine an edit with its check, fetch from a packed result instead of running the command again, search before reading a large file, keep commands short.

3. Compaction at the right time

  • Auto-compact ceiling. ekorn setup claude sets Claude Code's CLAUDE_CODE_AUTO_COMPACT_WINDOW (250000 by default), so the conversation is compacted at that size instead of growing to the model's full window.
  • Compaction advisor. At the end of a turn ekorn tells you when compacting would pay off, with the estimated tokens saved per request. It stays quiet otherwise.
  • Compaction by cache price (DeepSeek Harness). There the plugin does not advise, it acts: from the session's own token counts and the model's prices for cached input, uncached input and output it works out when a compaction pays for itself, and runs dsh's own compaction at the next idle moment. It leaves a context under a quarter of the model's window alone, because that compaction keeps nothing word for word. Nothing to configure.

4. Measure, then tune

  • Ledger. Hooks record every shell and read call (command shape and byte counts, never the output) and every compaction.
  • Report. ekorn report shows what share of large output was packed, what was missed, how often a summary had to be fetched back, and repeated full reads.
  • Suggestions. ekorn tune proposes threshold and pattern changes, each with its evidence and a replay of what it would have done. Apply and revert them one at a time, or let ekorn do it automatically within fixed limits; a change that makes things worse is rolled back.
  • Totals. ekorn probe adds up token use from your agent's session logs over a period and compares it with a saved baseline.

What each harness gets

Claude CodeCodex CLIDeepSeek Harness
Large output packedshell commands, before they runshell commands, before they runany tool's text result (except read), after it returns
Unbounded file reads cappedyesnono
Recallyesyesyes
edit_then_run, write_then_runyesyesno
Four rules at session startyesyesno
log-reducer sub-agentyes, on Haikunoyes, on deepseek-flash
Auto-compact ceilingwith setup claude; by hand with the pluginnodsh has its own (80% of the window)
Compaction advisoryesyesnot needed
Compaction by cache price, automaticnonoyes, for deepseek-flash and deepseek-v4-pro
Ledger, report, suggestionsevery shell and read callevery shell callpacked results and recalls
Core binaryyou install it (one command)you install it (one command)the plugin installs it
Checked onLinux, in daily usenot yet run in a live Codex installLinux command line with dsh 0.2.2-rc.1, including compaction and the log reducer against the real DeepSeek API; not yet Desktop, macOS or Windows

Install

DeepSeek Harness

Open Plugins → Add plugin and enter:

https://github.com/ekornhq/ekorn

That is the whole install; it needs git on the machine. The plugin downloads the core binary on first start and keeps it only if its checksum matches the one pinned in the plugin. Details and settings: plugins/dsh.

Claude Code

curl -fsSL https://raw.githubusercontent.com/ekornhq/ekorn/main/install.sh | sh

then, inside Claude Code:

/plugin marketplace add ekornhq/ekorn
/plugin install ekorn@ekorn

Or skip the plugin and let the core edit your configuration itself: add -s -- --setup after sh above (same as running ~/.ekorn/bin/ekorn-core setup claude). It writes the hooks and the CLAUDE_CODE_AUTO_COMPACT_WINDOW default into ~/.claude/settings.json, the token discipline into ~/.claude/CLAUDE.md (between and), the log-reducer agent and the MCP server. Every touched file is backed up first (*.ekorn-bak.), the command is idempotent, and setup claude --uninstall removes what it added; the archive stays.

Use the plugin or setup claude, not both: they register the same hooks, so installing both runs every hook twice and double-counts the ledger. The plugin cannot set CLAUDE_CODE_AUTO_COMPACT_WINDOW for you; set it in settings.json → env if you want it (setup claude uses 250000). More in plugins/claude.

Codex CLI

Run the same curl line as for Claude Code, then:

codex plugin marketplace add ekornhq/ekorn

Pick ekorn under /plugins and trust its hooks with /hooks. More in plugins/codex.

The core binary by hand

install.sh picks the binary for your OS and CPU (Linux and macOS), verifies it against sha256sums.txt, and puts it in ~/.ekorn/bin/ekorn-core. It installs nothing if the checksum does not match. -s -- --version v0.1.0 pins a release; EKORN_HOME changes the target directory. The same steps without the script:

os=$(uname -s | tr '[:upper:]' '[:lower:]'); arch=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
mkdir -p ~/.ekorn/bin && cd ~/.ekorn/bin
curl -fsSLO "https://github.com/ekornhq/ekorn/releases/latest/download/ekorn-core_${os}_${arch}"
curl -fsSLO  https://github.com/ekornhq/ekorn/releases/latest/download/sha256sums.txt
sha256sum -c --ignore-missing sha256sums.txt      # macOS: shasum -a 256 -c --ignore-missing sha256sums.txt
mv "ekorn-core_${os}_${arch}" ekorn-core && chmod +x ekorn-core
./ekorn-core --version                            # ekorn-core v0.1.0

Windows: download ekorn-core_windows_amd64.exe from Releases, check it against sha256sums.txt, and save it as %USERPROFILE%\.ekorn\bin\ekorn-core.exe.

Any other location works if you point EKORN_CORE at the file.

Check

~/.ekorn/bin/ekorn-core --version   # ekorn-core v0.1.0

A plugin's own ekorn --version prints that line and then ekorn shim 0.1.0 (…), which names the shell in play. Include both lines in bug reports.

Your data

  • The archive, the ledger and the policy file live under ~/.ekorn and nowhere else. The ledger is plain JSONL; it stores command shapes and byte counts, never tool output. Delete any of it whenever you like.
  • The core binary makes no network requests.
  • The only downloads are the core binary itself: by install.sh when you run it, or by the DeepSeek Harness plugin on first start (turn that off with autoInstall: false). Both fetch from this repository's Releases, verify a SHA-256, and send nothing about you or your sessions.

Commands

The plugins call these for you; they are also there to use by hand. ekorn below is the launcher a plugin ships, or ~/.ekorn/bin/ekorn-core.

ekorn pack --run '' [--timeout S]      # run, archive output >16 KiB, print the exact summary
ekorn pack --stdin [--label L]
ekorn recall  [--grep RE [-i] [-C N] | --lines A-B | --offset N] [--max-bytes N]
ekorn verify --source  --receipt     # verbatim check of a log-reducer receipt
ekorn report [--days N] [--json]            # coverage, missed packs, recall rate, repeated full reads
ekorn tune [--apply ID|all | --revert ID | --history | --explain ID | --auto on|off]
ekorn probe [--days N | --since DATE] [--json | --ledger | --compare baseline.json]
ekorn setup claude [--uninstall] [--autocompact N|auto] [--claude-dir DIR] [--no-mcp] [--auto yes|no]
ekorn rules                   # print the discipline text given to the model at session start
ekorn mcp                     # stdio MCP server: edit_then_run, write_then_run, obs_recall
ekorn hook session-start | pre-tool-use | post-tool-use | pre-compact | stop
ekorn --version               # ekorn-core 

Markers in the agent's context: a packed result starts with [ekorn-pack], a recalled slice with [ekorn-recall].

EKORN_HOMEdata directory, default ~/.ekorn (archive, ledger, policy)
EKORN_COREpath of the core binary; overrides $EKORN_HOME/bin/ekorn-core
EKORN_STOREarchive directory, if you want it elsewhere
EKORN_OFF=1turn ekorn off for this session
~/.ekorn/policy.jsonthresholds and wrap patterns; written by ekorn tune --apply, editable by hand (code default < policy < env)

This repository

ekorn is one core binary, ekorn-core, plus a thin shell per harness that forwards to it. This repository holds the shells and the installer; the core is published as a binary on Releases (v0.1.0: linux and darwin on amd64 and arm64, windows on amd64, with sha256sums.txt). The Claude Code and Codex shells do nothing without the core: their hooks exit silently and the agent behaves as before.

install.sh                        core installer for Linux and macOS
plugins/claude                    Claude Code plugin (hooks, MCP, agent, skill, launcher)
plugins/codex                     Codex plugin, portable Agent Plugins layout
plugins/dsh                       DeepSeek Harness plugin (packing, compaction by cache price, log reducer)
package.json, locale/             DeepSeek Harness bundle manifest, at the root so the repository URL installs
.claude-plugin/marketplace.json   Claude Code marketplace
.agents/plugins/marketplace.json  Codex marketplace
packages/npm, pypi, crates        `ekorn` command-line launchers; not yet published to the registries
.github/workflows/publish-shims.yml

License

Shells, launchers and documentation in this repository: MIT. The core binary is distributed under its own license. The packing approach was inspired by NVlabs/SoL-Pi (MIT); this is an independent implementation and contains none of its source.