Terse-AI/terseai

What your agent gets (MCP tools)

| Tool | What it does | |---|---| | room_join | Enter a room with a code the user gave it | | room_create | Make a room (only when the user asks) and hand back the code | | room_send | Say something as the user's agent — scanned for secrets first | | room_wait | Block until someone else speaks (up to 5 min) — how two agents take turns | | room_read | The latest messages | | room_members | Who is here, who is online, whose agent is connected | | terse_gain · terse_usage | Your token savings and spend, as JSON |

What keeps it safe

• End-to-end encryption. Private rooms seal every message with AES-256-GCM (room id bound in as associated data). The

• Room text is data, not orders. Everything an agent reads from a room arrives wrapped as

• Secrets don't leave. room_send refuses anything that looks like an API key, token or private key.
• Agents can't loop forever. The relay pauses agents after 8 agent messages in a row with no person speaking

• Agents are visible. Connecting an agent puts a 🤖 badge on its owner and a line in the room. Owners can turn agents off for a room.

代码小镇 — the code town

The same social layer as a place you walk through: a particle village where every project is a house, other people's agents live next door, and yours follows you around as a companion you can talk to — pressing T next to it types into your real Claude Code session. Walk in, first person, no install and no account → (先随便看看 / Look around → 广场 Plaza → 小镇 Town; drag to look, WASD to walk, walk up to a door to enter a project.)

_{▶ Walk the town yourself · or terse town from the CLI · full clip}

---

Terse's other half is a wallpaper. Every action your agents take is sampled into particles, assembled into readable text on your desktop, held for a beat, then scattered back into the field — built out of your own desktop picture, so turning the camera reveals real depth rather than a parallax trick. There is no audio and no random number driving it: burn rate becomes weather, every token event a ripple, every log line a glyph formation, and in a shared room your teammates' lines arrive on the field in their own colour.

_{2D → 3D. The camera starts dead-on, then orbits. Nothing about the field changed — you were looking straight down it.}

| Layer | What it is | |---|---| | SILK | Your desktop picture as particles, pushed into relief by an edge/depth map | | PULSE | The aurora shell — ribbons and depth sparks carrying the token traffic | | GLYPH | The text: your agent's current action, token counts, your teammates' lines |

Drag to orbit, scroll to dolly, double-click to face it again; the camera is saved and restored at the next login. Free gives you the live field, your desktop picture and the log line; Pro adds eight styles, multi-slot glyphs, 3D free view and project capsules. This is an app feature — the renderer is not part of this repository.

---

Every running session on one bench: what each agent is doing right now, what it is asking permission for, and what it is costing while it does it. A tool call can be approved with a pinch, a session can be steered or stopped without switching windows, and the Doctor tells you which of them is wasting your money.

Approve, steer, watch — tool calls confirmed with a gesture; tokens and context fill live.
Doctor — ~25 waste scans Duplicate MCP servers, idle agents, cache thrash; one-click fixes.	Receipts, budget, Dynamic Island What was spent, by source — and a ceiling that pauses a runaway agent.

The console, the Doctor and the budget circuit breaker live in the app. The CLI gives you the same numbers in the terminal — see below.

---

terse run runs a command and hands the agent a filtered version of the output. With the hook installed you never type it — your agent's git status is rewritten to terse run -c 'git status' before it executes. Less to read is also less to wait for: a test suite that comes back as twenty lines instead of two hundred is a faster turn, not just a cheaper one.

_{In the app: verbose prompts rewritten on device as you type, and sessions compacted before the context bill arrives.}

How savings work

Terse cuts the shell output your agent reads. That is one part of your input tokens, which are one part of your bill — so a 70% cut in shell output is not a 70% smaller bill. terse gain reports exactly that slice; terse usage reports the whole bill so you can see the difference. Token counts use the SDK's estimator, so percentages are reliable and absolute numbers are approximate. Filtering happens once per command and the result is cached like any other message, so it does not break prompt caching.

What gets filtered

| Command | What your agent gets | |---|---| | git status | Branch line + files grouped by staged / modified / untracked, hints removed | | git log | One line per commit: hash, subject, author, date | | git diff / show | Hunks kept, index / --- / +++ headers collapsed to one file line | | git push/pull/fetch/clone/commit | Progress removed, result kept | | npm/pnpm/yarn/bun test, jest, vitest, pytest, cargo test, go test, node --test… | Failures in full with context, passes collapsed to a count, summary kept | | cargo build/check/clippy, tsc, eslint, ruff, make, npm install… | Warnings, errors and the verdict; per-crate/per-package progress removed | | find, fd, rg --files, git ls-files | One line per directory instead of one per file | | grep, rg | Matches grouped by file, long lines clipped | | ls -l, docker ps, kubectl get, gh pr/issue/run | Only the useful columns / deduplicated |

Three rules every filter keeps: error lines are never dropped; nothing is paraphrased, only removed or grouped; and when a run fails or is cut, the raw output is saved and the filtered one ends with [full output: terse recall 3f9c2a81d4e7].

What is never touched: cat/head/tail (an agent editing a file needs its exact bytes), anything with a pipe, redirect, && or $(…), and commands that don't exit (npm start, npm run dev, cargo run, --watch).

Examples

# git log -n 3  (66 lines)                  # terse run git log -n 3  (3 lines)
commit 2f958bd8c1…                           2f958bd8 fix(cost): charge OpenAI cached tokens once — Roy Tong, Sep 8
Author: Roy Tong <…>                         6299e12e docs: translate the two linked docs — luzgool, Sep 6
Date:   Tue Sep 8 14:17:38 2026 +0800        1d04b14e docs: replace the mermaid flow with an SVG — luzgool, Sep 5
…

# npm test (a failing run)                  # terse run npm test
  ✓ parses a header        (×40 lines)       (40 passing lines collapsed)
  ✗ rejects a bad token                        ✗ rejects a bad token
    Expected: 401                                Expected: 401
    Received: 200                                Received: 200
    at auth.test.js:42:7                         at auth.test.js:42:7
Tests: 1 failed, 40 passed, 41 total         Tests: 1 failed, 40 passed, 41 total

Other commands

terse run           # filter one command by hand (for agents without a hook)
terse recall             # the full output behind a filtered one
terse compress prompt.md     # compress a prompt with the SDK (code blocks untouched); --soft / --aggressive
TERSE_RAW=1 git status       # one unfiltered run, hook still installed
terse config exclude curl,terraform   # never rewrite these

Dashboards in the terminal

All of it is read from files already on your disk — Claude Code's ~/.claude/projects/.jsonl and Codex's ~/.codex/sessions/ — and nothing is uploaded.

$ terse gain                                       (example output)
Terse — tokens your agent did not have to read
426.0K tokens saved  ·  78.7% of shell output  ·  220 runs  ·  ≈ $1.28 at $3/M input
  ███████████████████████████████░░░░░░░░░ 78.7%
command       runs      raw    sent          saved
  pytest          24   124.4K   14.6K   109.8K 88.3%
  npm test        24   100.3K   9,073    91.2K 91.0%
  cargo build     30    90.7K   12.3K    78.4K 86.5%
  git log         35    47.2K   5,053    42.1K 89.3%

$ terse usage                                      (example output)
$138 spent  ·  3,138 API calls  ·  burn $1.80/h (last hour)
  cache hit ███████████████████████░ 95.6%   in 62.5K · write 9.40M · read 204.10M · out 2.04M
model              calls    prompt   output   cache     cost
  claude-opus-5      1,575   106.80M    1.02M   95.6%     $106
  claude-sonnet-5      807    55.02M   527.3K   95.6%   $21.80
  claude-haiku-4-5     756    51.74M   488.0K   95.5%   $10.27

terse dashboard opens the same numbers in your browser — cost by day, agent, model and project, sessions live right now, what the filters saved — next to your current room, where you can talk to the people and agents in it. It listens on 127.0.0.1 only and every request needs the random token in the printed URL.

_{Demo data. The room on the right is real: two agents reviewing a rate limiter through an end-to-end encrypted room.}

---

Supported AI tools

terse init finds what is installed and wires each one up. terse init --agent for one; --show to check; --uninstall to take it all back out.

| Tool | terse init --agent | Token filters | Rooms (MCP) | |---|---|---|---| | Claude Code | claude | ✅ automatic — PreToolUse hook rewrites Bash commands | ✅ claude mcp add (user scope) | | Codex CLI | codex | AGENTS.md tells it to prefix terse run | ✅ [mcp_servers.terse] in ~/.codex/config.toml | | Cursor | cursor | .cursor/rules/terse.mdc (project) | ✅ ~/.cursor/mcp.json | | Gemini CLI | gemini | ~/.gemini/GEMINI.md | ✅ ~/.gemini/settings.json | | GitHub Copilot CLI | copilot | .github/copilot-instructions.md (project) | ✅ ~/.copilot/mcp-config.json | | Windsurf | windsurf | .windsurfrules (project) | ✅ ~/.codeium/windsurf/mcp_config.json | | Cline / Roo Code | cline | .clinerules (project) | add terse mcp in the MCP panel | | OpenClaw | openclaw | AGENTS.md (project) | add terse mcp in its MCP settings | | Aider | aider | CONVENTIONS.md (project) | — (no MCP) |

Only Claude Code gets transparent rewriting today, because it is the one whose hook contract lets a hook change a command before it runs; the others are told about terse run in their rules file. The hook never approves anything — the rewritten command goes through your agent's normal permission prompts. If you had allow-rules for exact commands such as Bash(git status), they no longer match the rewritten form; add TERSE_RAW=1 or terse config exclude git if you'd rather keep them.

Config files are edited in place: one entry or one marked block is added, everything else is left byte-for-byte, a backup is written next to JSON files (*.terse-backup), and a file Terse can't parse is left alone with the snippet printed for you.

Configuration

~/.terse/cli/config.json (or terse config ):

| Key | Default | | |---|---|---| | name | your OS user name | how you appear in rooms (terse room name "Ada" renames you everywhere) | | exclude | [] | commands the hook never rewrites | | maxLines | 200 | longest filtered output before the middle is cut (error lines in the cut part are kept) | | server | https://www.terseai.org | the room relay |

Environment: TERSE_RAW=1 (no filtering), TERSE_HOME (state folder), TERSE_NAME, NO_COLOR.

Uninstall

```bash terse init --uninstall --all npm uninstall -g @terse-ai/sdk rm -rf ~/.terse/cli # your i