Token-Goat Architecture & Engineering Q&A

Token-goat does not alter your prompt instructions. If you ask the agent to fix a bug, your message goes straight to the model word-for-word. The hooks only fire on two specific events: file reads and terminal command executions.

For terminal commands like npm test, token-goat folds 50 passing test lines into a single summary line and keeps only failing stack traces so you don't flood the prompt with green checkmarks.

The index runs automatically in the background in your local development environment whenever files are saved or modified, just like VS Code's local search index. It does not send your code to any cloud API; it uses a small local model (bge-small-en-v1.5, ~35 MB).

• What is indexed: Function signatures, class definitions, method bodies, type declarations, docstrings, and markdown docs across 80+ languages.
• What is strictly ignored: Your node_modules/ folder, build output folders (dist/, target/), compiled binaries, and .git internals.

What triggers this command? (From User Prompt to AI Execution)

The AI model does not randomly guess the command. It is directed and enforced through three cooperating mechanisms:

1. The Guidance Gate (System Instructions): When token-goat install runs, it adds clear rules to the agent's instructions (in CLAUDE.md or Copilot system prompt). One explicit rule states: "Searching for a concept rather than a literal string? Use token-goat semantic <description> instead of dumping files or running broad grep." When you ask "where do we refresh the oauth session?", the model recognizes this as a conceptual query and chooses token-goat semantic.
2. The Runtime preToolUse Hook (Enforcement Net): If the agent forgets and tries to brute-force a file dump with native view("src/auth.ts") (1,200 lines), token-goat's registered pre-tool hook halts the call before disk access:
   Denied by preToolUse hook: [tg] File exceeds threshold (1,200 lines).
   Use token-goat semantic to locate the relevant function, or read "file::symbol".
   The model reads the denial, immediately self-corrects, and executes token-goat semantic.
3. Native MCP Tool Schema (VS Code & Claude Desktop): In VS Code or Claude Desktop (via token-goat install --vscode), semantic search is registered directly as a native Model Context Protocol (MCP) tool (semantic_search) with a JSON schema description. The model's function-calling mechanism selects it directly based on your prompt intent.

User Prompt: "Where do we refresh the oauth session?"
     │
     ▼
[Stage 1: System Instruction Gate]
  LLM checks rules: "Searching for a concept, not a literal symbol?
  Rule: Run `token-goat semantic <description>` instead of broad grep."
     │
     ├──► (Happy Path) ──► Agent executes: `token-goat semantic "where do we refresh the oauth session?"`
     │
     └──► (Fallback: Agent tries `view("src/auth.ts")` on 1,200-line file)
             │
             ▼
          [Stage 2: Runtime preToolUse Hook Intercepts]
          Hook denies read: "File exceeds threshold. Use `token-goat semantic` or `read file::symbol`"
             │
             ▼
          Agent self-corrects and calls: `token-goat semantic "where do we refresh the oauth session?"`

In a long session (like fixing a tricky bug or refactoring an API), the agent carries every previous turn in its memory. Every time an agent reads a file, that entire file stays in context on every single subsequent turn, compounding session size exponentially.

The agent does not get confused, avoids hitting hourly rate limits, and responds in seconds instead of minutes.

This is the most common counter-argument from engineers familiar with Anthropic or OpenAI prompt caching. On paper, cached prompt tokens receive a discount of 90% or more. In production engineering workflows, prompt caching does not eliminate the penalty of context bloat for five concrete reasons:

1. The 5-Minute Eviction TTL (Developer Thinking Time): Anthropic's prompt cache lives 5 minutes by default, refreshed each time it is read; a one-hour cache is available at twice the base price to write. Other providers expire cached prompts on their own schedules. Real engineering work is not an automated batch script. You stop to review a git diff, inspect a compiler error, run a local debugger, test an endpoint in Postman, or think through a design choice. Once a pause outlasts the cache, the next turn writes the whole prompt again: all 85,000 tokens at 1.25x the base input price on Anthropic's five-minute cache, or 2x on the one-hour one.
2. Prefix Invalidation (What Changes Earlier in the Prompt): Prompt caching is a prefix cache: a cached prefix is reused up to the first token that differs. Appending to the conversation, whether an edit's result or a tool output carrying a timestamp, leaves everything before it cached. A change earlier in the prompt does not: a different system prompt, a model switch, or a change to the tool definitions (connecting or disconnecting an MCP server changes them) makes every token after that point a cache write again.
3. Context Window Ceilings & Lossy Auto-Compaction: A 90% billing discount does not expand the physical context window. When an agent fills 150,000 tokens with full-file dumps, you hit the context limit. The harness triggers aggressive, lossy auto-compaction (dropping earlier turns, forgetting constraints, and losing instructions). Organizational rate limits (Tokens Per Minute, or TPM) also measure total token volume regardless of cache status. An agent pushing 85,000 tokens per turn rapidly triggers 429 Rate Limit Exceeded errors across your team.
4. Attention Dilution ("Lost in the Middle"): Transformers are not relational databases with index pointers. When an LLM evaluates code across 85,000 tokens of mostly irrelevant CSS, boilerplate imports, and unrelated methods, self-attention is diluted. Needle-in-a-haystack retrieval degrades, causing the model to miss edge cases, forget constraints, or hallucinate bugs. Keeping context lean (11,500 tokens) delivers measurably higher code accuracy than bloated context (85,000 tokens), even if those extra tokens were zero dollars.
5. Prefill Latency (Wait Time): Even on warm cache hits, processing an 85,000-token prompt adds 3 to 6 seconds of prefill latency. On cold turns after a 5-minute pause, prefill can take 12 to 15 seconds before the first token streams. A surgical 11,500-token session responds in under 2 seconds.

It depends entirely on whether the one-shot question touches local files. In a single-turn session, token-goat either slightly increases cost by about 26% (for pure zero-file trivia) or cuts cost substantially (the moment it touches code, a PRD spec, an Excel sheet, or a PDF) thanks to first-read savings:

In short: for pure conversational trivia, it adds ~900 tokens (~26% overhead). For any task that touches a workspace file (whether code, markdown specifications, Excel models, PDF contracts, or OpenAPI JSON), first-read savings pay back the 900-token instruction block immediately and cut token burn by roughly 60% to 90% on turn 1, measured across the project’s own surgical-read benchmark cases.

The stats dashboard shows exact numbers tracked by your local SQLite database (src/stats.ts). Run token-goat stats --full in your project root to see your savings.

Token-goat runs 100% locally in your development environment. By design, it does not connect to Anthropic, OpenAI, or your company's private billing portal, and it does not know what went through the enterprise cloud cache or how the provider resolved cache hits. It knows with byte-for-byte precision how many raw tokens it stopped from ever entering the prompt over the network, but it cannot know your cloud provider's internal billing or server-side cache state without spying on your private API traffic.

Attempting to capture that telemetry would also actively slow down your development loop. Tracking exact cloud cache percentages would require running a local proxy, decrypting every streaming TLS API payload to inspect provider response headers, or making synchronous HTTP calls to enterprise billing endpoints on every turn. That kind of heavy network telemetry adds latency, creates failure modes, and violates security boundaries.

Instead, token-goat records telemetry as simple in-process SQLite WAL counter increments that execute in under 0.2 milliseconds with zero network traffic. You get fast local accounting without slowing down your tools.

You can easily calculate your percentage for any session:

No. They serve completely different purposes in the developer workflow:

• VS Code Copilot's index is a search tool: It indexes files to help the agent find which file might be relevant when you type @workspace. But once VS Code finds the file, it has no mechanism to control context: it dumps the entire file into the conversation prompt.
• Token-goat is a runtime execution gatekeeper: It builds an AST symbol and call graph using Tree-sitter across 80+ languages to locate exact function, class, and method boundaries. When the agent attempts to read a 2,500-line file, token-goat intercepts the call and serves only the 30-line function needed.

VS Code helps the model find the file; token-goat prevents that file from flooding your context window.

No. Token-goat produces massive net savings on both system resources and token costs:

1. Tiny local footprint: Token-goat runs locally against an embedded SQLite WAL database, with no server and no compile step: CLI invocations are short-lived processes, and the only resident piece is the background reindex worker. Each hook check is a short-lived subprocess costing roughly 130 milliseconds, small against a 2,000-millisecond API round-trip.
2. Massive token ROI on first read: The moment Copilot or any agent reads a file, token-goat cuts prompt consumption by 80% on average across the project’s own benchmark cases, and by more than 90% on a large file, paying for its background index many times over on the very first turn.
3. Protects what VS Code ignores: VS Code's index does not deduplicate re-reads of unchanged files, does not fold noisy terminal command output (like 500 lines of passing tests), does not slice PDFs or spreadsheets, and does not operate outside VS Code (such as in Claude Code, Copilot CLI, Codex, or Cursor). Token-goat protects your context across all of them.

The simple analogy: VS Code is the librarian who pulls the book from the shelf. Token-goat is the highlighter that shows the model just the paragraph it needs so the agent does not photocopy the entire 500-page book into prompt memory.

If an individual harness ever replicates a specific token-goat capability natively, token-goat already has built-in adaptive bridge detection (src/bridges/registry.ts). It dynamically detects native harness features and yields its own hook for that specific operation. There is zero redundant execution.

However, expecting commercial harnesses to solve this enterprise-wide ignores three structural realities:

1. The Provider Incentive Conflict: Model providers (Anthropic, OpenAI, hyperscalers) generate revenue by billing for ingested tokens. A model provider's harness has no business incentive to slash billable token volume by 85% to 97% across your organization. Token-goat works exclusively for the customer.
2. Cross-Harness Portability: Engineering teams never use a single tool. If Copilot in VS Code adds a feature, it does not help engineers running Claude Code in the CLI, Cursor, Windsurf, or automated CI pipelines. Token-goat provides a unified, cross-harness context engine with one shared index, security boundary, and configuration across every tool you run.
3. Full-Stack Scope Beyond Raw Code: Harnesses treat files as generic text. Token-goat is a multi-format context engine: AST symbol slicing across 80+ languages, token-aware PDF/Excel/Word extraction, automated image downsampling, and a local SQLite index that answers without a language server or a build.

Token-goat is built on proprietary patented intellectual property covering runtime AST surgical extraction, execution interception hooks, and cross-session context compaction. It is not an ad-hoc bash wrapper or a short-lived monkey patch.

The patent protects the core pipeline: using in-process Tree-sitter AST parsing to map exact function and class boundaries across 80+ languages, intercepting runtime file reads before disk I/O, and substituting precise symbol slices without model drift. This architecture delivers deterministic, byte-accurate code extraction that generalist harnesses cannot replicate without licensing protected IP.

Even with 1M+ token context windows standard across frontier models, putting 100,000 lines of code into a prompt degrades model quality. Research across SWE-bench and frontier model evals proves that LLMs suffer from 'lost in the middle' syndrome: when given too much noise, they hallucinate, miss subtle bugs, or edit the wrong file.

Lead Engineer Recommendation: My practical advice for everyday developers is not to touch anything. Token-goat ships with safe, battle-tested defaults that require zero configuration to start saving tokens immediately. Tuning config files adds friction you do not need on day one.

What SecOps Suggests (and Why): If SecOps or enterprise compliance mandates a hardened profile for sensitive repositories, here is why SecOps suggests each line in Security Lead's snippet and how to evaluate it:

• confine_reads_to_project_root = true: Approved by SecOps. Prevents an agent from reading files outside your repo (like ../../.ssh/id_rsa or ../../.aws/credentials).
• allowed_roots = ["C:/dev"]: Approved by SecOps. Pins authorized agent workspace paths to your dev folder.
• strict = true: SecOps favorite with an engineering advisory. Automatically redacts passwords and secrets from prompts. Keep in mind that 40-character git commit SHAs can occasionally trigger false-positive entropy filters.
• block_private_targets = true: Approved by SecOps. Prevents the screenshot tool from probing internal private IP addresses (like 192.168.x.x or 10.x.x.x).

SecOps often pushes for offline = true to guarantee zero outbound network traffic. That is great for compliance, but applying it immediately on a clean install creates a problem: token-goat needs to download its small local embedding model (bge-small-en-v1.5, ~35 MB) once to power semantic search.

Shouldn't install cache the model automatically? Yes, and automated fail-soft background pre-caching is the default path. However, token-goat install is intentionally decoupled from blocking downloads so the command never hangs or crashes if run offline, in air-gapped CI, or behind a strict proxy.

If you turn on offline = true before that model is cached locally, semantic search fails. Here is how to satisfy SecOps cleanly:

Yes, token-goat maintains a complete code relationship graph in its local SQLite database (refs table). It does not just index text; it parses code into syntax trees to track:

• Callers & Callees: Which functions call which other functions.
• Inheritance: Which classes extend or implement an interface.
• Impact Analysis: What breaks if you change a function signature.

In theory, pairing architectural memory with token-goat is a natural division of labor: memory maps relationships, and token-goat extracts the exact code. But in production, running generic MCP codebase-memory tools burns massive context through three specific failure modes:

1. The Permanent System Prompt Schema Tax:
Registering an MCP server forces the harness to inject full JSON-schema definitions for every tool into the system prompt on every single turn. Declaring standard memory tools (create_entities, create_relations, add_observations, read_graph, search_nodes) costs on the order of a thousand tokens. In a 20-turn session that whole cost is re-billed every turn, just for the tools to sit idle in context.

2. The JSON Syntax & Entity Dump Tax:
When queried, generic memory servers return sprawling JSON payloads where over 40% of the tokens are syntactic scaffolding (brackets, quotes, property keys):

{
  "entities": [
    {
      "name": "AuthService",
      "entityType": "class",
      "observations": [
        "Handles OAuth2 session refresh and JWT token verification",
        "Located in src/auth/service.ts, exported as default class",
        "Code snapshot: async refreshSession(token) { const res = await fetch('/oauth/token'); return res.json(); ... [40 lines of static code copied into memory] }"
      ]
    }
  ],
  "relations": [
    {"from": "AuthService", "to": "UserController", "relationType": "injected_into"},
    {"from": "AuthService", "to": "RedisSessionStore", "relationType": "queries"}
  ]
}

3. The Stale Inlined Snippet Trap (Cascading Re-Reads):
Notice the static code snippet inside the observation above. The moment an engineer updates refreshSession() on disk, that memory snapshot rots. The agent generates code based on the obsolete signature, fails the build, and then reads the entire 2,000-line file with view to recover. A single memory lookup ends up costing 6,000+ tokens in wasted syntax, errors, and emergency whole-file reads.

Project Note & Compliance Status: token-goat-mem is a separate open source project of mine created to demonstrate token-budgeted memory architecture. It has not undergone formal enterprise IT or SecOps review yet, so it is not packaged for company-wide deployment. However, its architectural model demonstrates how memory systems must be built to prevent context bloat:

Rather than burning thousands of tokens on external MCP JSON overhead, token-goat-mem was designed specifically around token-first discipline:

1. Symbol Pointers Instead of Inlined Code: token-goat-mem never stores raw code blobs. It stores surgical pointers (e.g. src/billing/stripe_webhook.ts::handleInvoicePayment). When the agent needs the code, it resolves the pointer live via AST slice. You get 100% current code with zero stale context bloat.
2. Zero MCP Schema Tax: Integrated through native hooks and local CLI rather than bloated JSON-RPC schemas, so no per-turn tool-declaration schema is re-sent with every request.
3. Compaction-Resilient Epoch Tracking: Deeply wired into token-goat's compaction engine (src/hooks_compact.ts). During long-running sessions, memory state tracks across mem epoch counters, ensuring durable state survives agent context compaction without dumping sprawling history transcripts.
4. Sub-200 Token Output Footprint: Designed to return structured facts in plain text rather than multi-kilobyte JSON-RPC trees, aiming to keep memory retrieval cheap.

The 403 Forbidden error is an infrastructure permission failure from the enterprise package feed (Artifactory, Azure DevOps Artifacts, or Nexus), not a defect in the repository or installation instructions. I do not maintain our corporate Artifactory feed; that infrastructure is owned and managed exclusively by Central IT and DevOps. Because access is gated by corporate directory permissions, filing an SCM issue against token-goat cannot grant you registry credentials.

The error simply means your terminal's npm attempted to pull a scoped private package (@enterprise/token-goat) without an authenticated company SSO token or personal access token.

You do not need to file an IT ticket or wait days for Artifactory permissions. The fastest path is simply asking your AI coding assistant to handle it. If you prefer manual commands, options 2 and 3 get you running immediately:

Token-goat has a strict architectural rule: it never rewrites, rephrases, or edits your user prompts. If you type "Refactor calculateDiscount to use the new customer tier rules", that exact string goes to the model.

Token-goat is a filter on outputs (preventing 3,000-line files from flooding into context), not an editor of your input or intentions.

When token-goat serves a function slice via token-goat read "src/pricing.ts::calculateDiscount", it does not summarize code or rewrite syntax. It reads the exact lines from your source file on disk using Tree-sitter line boundaries.

Claiming an arbitrary number like "+20% code quality" without a reproducible benchmark would be marketing spin. Code quality is multidimensional, measured across compiler errors, test pass rates, diff sprawl, and multi-turn reasoning consistency.

Token-Goat does not make the underlying neural network smarter. It does not alter model weights, invent new reasoning capabilities, or perform lossy AI summarization on source code. When Token-Goat extracts a symbol (such as token-goat read "orderService.ts::calculateDiscount"), it extracts the exact, byte-for-byte AST block directly from disk.

Token-Goat works by eliminating context pollution, preventing the well-documented reasoning degradation that occurs when an LLM is flooded with thousands of lines of irrelevant code.

The one head-to-head evaluation this project has actually run is a cost measurement, not a code-quality study. It is a paired A/B design: one real bug per repository snapshot, a single model (claude-sonnet-5), a single repository (this one), with the two arms differing only in the tool surface offered to the model:

Evaluation Setup: In Arm A (Baseline), the agent used conventional whole-file reads and text search (read_file, grep, list_files) alongside edit_file and run_tests. In Arm B (With Token-Goat), read_file and grep were replaced with token-goat's surgical read commands (tg_read, tg_symbol, tg_outline, tg_section, tg_semantic, tg_refs), keeping the same edit_file and run_tests. Cost is counted as billing-weighted input tokens (fresh 1.0x, cache write 1.25x, cache read 0.1x), summed over every turn, with no estimator involved. Raw data: demo/data/eval-runs.csv and demo/data/eval-tasks.csv. Full capture: demo/evidence/12-eval-paired.txt, whose figures tests/eval_capture_matches_data.test.ts recomputes independently from the CSVs on every npm test run.

This is a cost result only. Every one of the 8 recorded pairs resolved in both arms, so the evaluation says nothing about output quality, capability, or correctness, only about how many billed tokens each arm consumed reaching the same outcome. It also carries real limitations: n=6 is small enough that the median moves under single-pair changes (the clean per-pair ratios run 0.109, 0.247, 0.261, 0.459, 0.612, 1.265), two pairs were excluded post hoc for writer contamination using a mechanical but not pre-registered criterion, and the run is single-model, single-repository, with tasks authored by this project rather than an independent benchmark.

If you want to review the external empirical data and peer-reviewed research confirming that context pruning improves LLM reasoning, here are four foundational papers:

Roslyn is Microsoft's C# compiler platform. It is hosted in IDEs like Visual Studio to provide complete semantic type-checking, cross-assembly symbol binding, refactoring analyzers, and compiler diagnostics. However, Roslyn has strict structural constraints: it requires a valid, buildable project (.sln or .csproj), consumes hundreds of megabytes to over a gigabyte of memory, and only supports C# and VB.NET.

Token-Goat is not an LSP replacement; it is a runtime context gatekeeper. It parses source code using Tree-sitter AST and SQLite across 80+ languages without compiling anything, needs no project model or successful build to answer, and functions reliably even when the codebase is in a broken or unbuildable state.

Roslyn provides compiler truth, while Token-Goat protects the agent's context window. Here is an exact walk-through of how they work together during a real refactoring task:

✓ The division of labor: Roslyn enforces strict compiler type correctness; Token-Goat ensures the agent's context window is never exhausted by verbose compiler logs or massive source files.

At install time, token-goat writes approximately 900 tokens of routing instructions into your agent instruction file, where they are re-read on every session. These instructions teach the agent how to use surgical commands (such as token-goat read "file::symbol") and fold terminal output.

If you run a trivial one-turn query (like asking "what is a JavaScript promise?" where the agent reads no files and runs no commands), those 500 tokens are net overhead on that single turn. However, teams across engineering, QA, DevOps, data, and product do not use AI assistants for one-turn trivia. You use them to inspect repositories, trace pipelines, review PRDs, examine spreadsheets, run test suites, and debug complex multi-file systems. The moment your agent reads any workspace file (code, a markdown PRD, an Excel sheet, a PDF, or terminal logs), that initial 900-token investment pays immediate dividends.

Consider the exact token math on a standard multi-turn debugging session:

[HttpPut("{id}/email")]
[Authorize]
public async Task<IActionResult> UpdateEmail(string id, [FromBody] UpdateEmailDto dto) {
    if (!ModelState.IsValid) return BadRequest(ModelState);
    if (!Regex.IsMatch(dto.NewEmail, @"^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$")) {
        return BadRequest("Invalid email format.");
    }
    var result = await _userService.ChangeEmailAsync(id, dto.NewEmail);
    return result.Success ? Ok() : StatusCode(500, result.Error);
}

Denied by preToolUse hook: [tg] Every line of UserController.cs this read
would return was already served in this session, byte for byte.
Recall it with `token-goat bash-output 9e3dc1a7b8145429`, or pull just the
part you need with `token-goat read "UserController.cs::Symbol"`.

[token-goat: folded 14 passing test suites (2,410 tokens elided). Showing 1 failure:]
FAIL tests/user_controller.test.ts > UserController > UpdateEmail > accepts plus addressing
AssertionError: expected 200 "OK" but received 400 "Invalid email format."
   at Object.<anonymous> (tests/user_controller.test.ts:74:18)
Suites: 1 failed, 14 passed, 15 total
Tests:  1 failed, 81 passed, 82 total

You do not have to take anyone's word for it. Run token-goat stats --full in your terminal at any time. It outputs an exact audit from your local SQLite tracking database (src/stats.ts): total raw tokens requested, tokens actually delivered to the model, total tokens saved, and the count of intercepted file reads and compressed terminal outputs. If your session is touching real code, you will see thousands of tokens saved within your first five minutes.

No. The interception hooks (src/hooks_read.ts, src/hooks_session.ts) are compiled TypeScript running locally against SQLite in WAL mode. The harness spawns one short-lived subprocess per hook fire, so when a tool call fires, token-goat checks the file hash and SQLite symbol cache in about 130 milliseconds (measured on an idle Windows machine, of which roughly 40 ms is Node.js startup itself).

For perspective, the network round-trip to the Anthropic or OpenAI API takes between 1,500 and 4,000 milliseconds, so a 130-millisecond local check adds 3% to 9% on top of a round-trip you are already paying. That is a real cost, not a free one, and it is worth it only because the tokens it removes shorten the round-trip it sits in front of.

Telemetry and stats collection are equally lightweight: counters are recorded via local atomic SQLite increments taking under 0.2 milliseconds. There are no remote analytics pings, no background HTTP beacons, and no network calls blocking your workflow.

The real cause of agent slowness is context window bloat. Large Language Models must compute attention across every single token in their history before outputting their first word (known as Time To First Token, or TTFT). When an agent dumps full 2,000-line files and verbose build logs into the context, history balloons to 60,000 or 100,000 tokens.

A local check costing a fraction of a second saves you seconds of waiting on every single turn. Token-goat makes your sessions substantially faster overall.

If you ran a cold index on day one and heard your fans spin up while your PC slowed down, you were not imagining it. First-time users encounter this lag because Token-Goat is generating local neural embeddings across the entire repository. However, this is a strictly one-time cold cost that permanently disappears on all subsequent sessions.

Here is why that initial lag occurs and why you never pay it again:

• Why the Initial Pass Takes Minutes (Local Neural Inference): To power semantic code search (token-goat semantic), Token-Goat runs a local 384-dimensional transformer model (Xenova/bge-small-en-v1.5 via ONNX Runtime in src/embed_model.ts). For every symbol and markdown chunk in the repository, it executes a neural network forward pass directly on your CPU:
  • A typical enterprise repository contains 8,000 to 15,000 code symbols and doc sections.
  • Each one needs its own forward pass, so a cold index is minutes of sustained tensor matrix math rather than seconds.
  • By default, ONNX Runtime attempts to parallelize across available CPU threads (worker.embed_threads), saturating multi-core workstations and triggering Windows Defender real-time scans on SQLite database churn.
• Why the Lag Permanently Disappears (Incremental SHA Fingerprinting): Once that initial baseline is written to SQLite, Token-Goat stores cryptographic SHA-256 hashes of every file and its parser/embedding state (src/fingerprint.ts). On every future session:
  • Unchanged files are detected by SHA comparison and skipped without being reparsed.
  • When you edit code, only that specific modified file is incrementally parsed and re-embedded in the background.
  • Session startup drift detection (src/reconcile.ts) enforces a hard 1,500ms wall-clock ceiling, ensuring daily session launches remain instant.
  In short: you pay the compute cost once per codebase; all daily work thereafter runs with zero CPU lag.
• Your Interactive Agent Session is Never Blocked: Even during that first-time cold run, the session startup hook (src/hooks_session_start.ts) finishes well inside that ceiling: about 0.3 seconds measured on an idle Windows machine, more under load. Terminal output folding, read deduplication, and image shrinking require zero embeddings and zero index. They function at 100% efficiency on prompt 1.

You can eliminate workstation lag completely using two simple configuration settings in your token-goat.toml:

[worker]
embed_threads = 1
priority = "below_normal" # or "low"

[indexing]
embeddings_enabled = false

Additional Hygiene Check: Verify that unignored build output like node_modules/, dist/, or .venv/ are not being indexed. Run token-goat doctor; if the database has exceeded 1 GB due to indexing minified vendor bundles, run token-goat reclaim-index --rebuild to restore SQLite to minimal size.

In src/hooks_bash.ts, maybeCompressRewrite wraps recognized single commands into token-goat compress -f <filter> --timeout <sec> -c '<rawCmd>'. The acceptance criteria for semantic equivalence are strictly verified by invariants:

• Exit Code Invariance: The wrapper executes the original command as a real child process and propagates the exact exit status code (e.g. 0, 1, 137) and signal to the harness. A test failure remains a test failure; a syntax error remains a syntax error.
• Pipeline & Control Operator Safety: The hook strictly rejects commands with shell control operators (|, ||, &&, ;, >, >>). If an agent runs a pipeline, isCompressibleSingleCommand() returns false and the hook yields null, leaving the harness to execute the original command completely untouched.
• Environment & Working Directory Preservation: Arguments, environment variables, working directory (cwd), and shell pathing are passed through byte-for-byte without interpolation or stripping.

In src/hooks_agent_spawn.ts, the preAgentHandler handles agent spawn tool calls (such as Claude Code's Agent or Copilot CLI's task). The prompt rewriting acceptance criteria are:

• Strict Append-Only Formulation: The code executes updatedPrompt = prompt + briefing + advisory. The agent's original prompt is never prepended, sliced, reworded, or token-pruned. It remains the opening anchor of the subagent's instructions.
• Navigation Briefing Injection: The appended briefing injects a high-density, compact repository map (symbol layout) and the token-goat surgical read gate rules. This prevents the subagent from burning 50,000 tokens performing recursive directory scans.
• Duplicate Spawn Advisory: If a subagent with a near-identical prompt (Jaccard similarity > 0.8) is already running this session, it appends an advisory note ([token-goat] A similar subagent spawn already appears to be outstanding...) to prevent accidental infinite spawn loops.

How does a developer observe or disable rewrites, and when does token-goat automatically decline to rewrite input?

1. Visible in Tool Call Headers: Both Claude Code and Copilot CLI render updatedInput directly in the CLI transcript. When a bash command is wrapped, the terminal card displays token-goat compress -f ... -c 'npm test' rather than bare npm test.
2. Audit Log Tracking: Run token-goat stats --full or inspect ~/.local/share/token-goat/global.db (table tool_events) to audit every rewrite event and recorded token delta.
3. Manual Opt-Out: If an atypical command fails under wrapping, developers can disable bash compression instantly by setting TOKEN_GOAT_BASH_COMPRESS=0 or setting [bash_compress] enabled = false in token-goat.toml. Specific filters can also be individually disabled via disabled_filters.
4. Automatic Engine Bypasses (Fail-Open Safety): Token-goat checks command suitability and declines rewriting whenever wrapping could alter shell semantics:
   • Pipelined and Compound Commands (src/hooks_bash.ts:1806-1847): Commands with unquoted operators (|, &&, ||, ;), command substitutions ($(), backticks), background operators (&), or I/O redirection (>, <) are rejected by isCompressibleSingleCommand and detectFromCommand.
     Concrete example: npm test | grep FAIL or pytest tests/ && git status.
     Engine behavior: Token-goat returns null from maybeCompressRewrite, running the original command bare. Wrapping a pipeline inside token-goat compress -c '...' would alter exit code propagation and pipe stream buffering.
   • Credential and Mutating Network Requests (src/hooks_bash.ts:1669-1689): In curlHasUnsafeFlags, curl commands bearing authorization headers (-H "Authorization: ..."), auth flags (-u), or mutating request payloads (-d, -X POST) are bypassed completely to prevent token leaks and state alterations.
   • Missing POSIX Shell Environments: On Windows without Git Bash, canRunWrappedShell() returns false, allowing commands to run directly in harness bash rather than breaking under cmd.exe.
   • Subagent Spawns (src/hooks_agent_spawn.ts:171-205): The prompt hook only ever appends context (prompt + briefing + advisory). It never truncates or rewrites agent instructions, and fails open (passOutput()) on any unexpected exception.

You're quoting what it says in the file docs/benchmark-baseline-2026-05-24.md, where it contains an explicit notice at the very top:

The active, fully reproducible benchmark suite is tests/token_savings_benchmark.test.ts running under Vitest. It asserts deterministic savings floors against real TypeScript fixtures and the built dist/token-goat.mjs bundle on every CI run.

Prior Inquiry Cross-Reference: This question was previously asked and answered in Q-11 (Principal Systems Architect): "It's clear that there are evals on tokens saved. Are there evals on model outputs, e.g. generated code quality, with and w/o token-goat?" Refer to Q-11's deep dive for the actual cost-only paired evaluation (64.0% median billing-weighted saving, n=6) and the cited external research on context attention degradation.

As established in Q-11, token-goat's automated benchmarks test context volume reduction and structural invariants (capping symbol body sizes, preserving function signatures in folded ASTs, and compressing passing suites without dropping error lines). They do not evaluate model reasoning output quality because token-goat is an infrastructure governor, not an LLM model provider.

However, from cognitive architecture research, pruning context bloat empirically improves model output quality:

• Eliminating "Lost in the Middle" Attention Degradation: When an LLM prompt is flooded with 50,000+ tokens of noisy build logs and unpruned source files, frontier models suffer severe needle-in-a-haystack retrieval and multi-hop reasoning degradation.
  Read Paper: Liu et al., "Lost in the Middle: How Language Models Use Long Contexts" (TACL 2024 / arXiv:2307.03172) ↗
• Preventing Collateral Diff Sprawl & Regressions: Giving an agent a 2,000-line file to edit a 5-line bug often causes accidental whitespace churn, comment alteration, and regressions in neighboring untouched methods. Precision retrieval over bulk file reads directly elevates real-world task resolution.
  Read Paper: Jimenez et al., "SWE-bench: Can Language Models Resolve Real-World GitHub Issues?" (ICLR 2024 / arXiv:2310.06770) ↗
• Repo Maps vs. Whole-File Context: Aider's own writeup argues that sending whole files wastes context window space, and that a tags-based repo map (classes, methods, and signatures across the repo) lets a model infer usage and architecture, and choose which files to look at more closely, without needing every implementation body. No specific pass-rate or token-reduction percentage is published in that source.
  Read: Paul Gauthier, "How Aider Creates a Map of Your Codebase" ↗
• Long-Context Attention Dilution (NIAH): Empirical context pressure testing confirms that even modern 1M+ token frontier models exhibit attention degradation and hallucination as prompt noise and distracting tokens accumulate.
  View Benchmark: Greg Kamradt, "Needle In A Haystack — Pressure Testing LLMs" ↗

This technical Q&A covers the architecture, mechanics, and verifiable behavior of Token-Goat itself, not corporate policy or organizational governance.

Decisions regarding who owns an enterprise A/B trial across corporate repositories, who executes evaluations, and what regression threshold leadership is willing to accept in exchange for token savings are corporate policy and management questions that must be addressed through your chain of command.

From an engineering perspective, Token-Goat provides the runtime instrumentation and fail-safes needed if your team chooses to evaluate it:

• Verifiable Invariants: Token-Goat's test suites enforce that tool output compression preserves error lines, respects shell command syntax, and prevents truncation (tests/guards/, tests/command_matrix_e2e.*.test.ts).
• Runtime Telemetry: token-goat stats and the local SQLite database track invocation counts, cache hit rates, and estimated byte/token savings.
• Total Bypass Controls: Any developer or automated workflow can bypass the tool entirely via environment flags (TOKEN_GOAT_DISABLE=1), configuration settings (config-set hooks.bash false), or unquoted shell compound operators.

For rollout approvals, risk-tolerance criteria, and internal team ownership, consult your team lead and engineering leadership.

In src/hooks_skill.ts, preSkillHandler monitors invocations of the Skill tool. When an agent calls Skill("superman") or Skill("pdf"), token-goat records the skill body in session cache.

If the model issues a repeat call to the exact same skill later in the same session, hasSessionOutput(event.sessionId, skillName) returns true. Loading a 40 KB skill document (on the order of 10,000 tokens) a second time wastes budget for rules already present in context memory.

If the agent experiences context compaction (summarization) and the summary accidentally drops detailed skill rules, does the model hallucinate based on a 400-token compact?

No, because the interception is not a silent stub. It returns an explicit denial message that instructs the model exactly how to recover the full body:

The model is immediately aware that it received an advisory, and if it requires the full body or a specific checklist (e.g. accessibility.md), it runs token-goat skill-body superman via terminal, which is never blocked and returns the complete text.

How is this detected rather than inferred after the fact?

• Telemetry Tracking: Every blocked repeat load increments the atomic stat skill-reload-deny in SQLite. Running token-goat stats --full displays the exact count of denied repeat loads and tokens withheld.
• Configuration Opt-Out: If a team or project prefers unconstrained raw skill loading on every invocation, set:

  [hints]
  pre_skill_advisory = false

  With this flag set to false, repeat skill loads pass through with 100% full-body injection every time.

As documented in docs/security.md and verified by tests/project_config_locked_sections.test.ts, a repository's local .token-goat.toml is strictly forbidden from setting exclusion keys:

This security rule was created specifically to eliminate the silent false-negative attack vector: an untrusted repository cannot blind the AI agent by excluding its own malicious code or sensitive auth routines from the index.

In the enterprise baseline, exclusions are strictly confined to build artifacts, package managers, and binary caches:

Zero application source files, controllers, services, database schemas, or internal documentation are ever excluded.

Developers and agents distinguish unindexed files through three concrete mechanisms:

1. The Agent Gate Exemption Rule: As documented in CLAUDE.md and system instructions: "Exemptions (gate passes, read directly): the file was never indexed (new, untracked, or generated this turn) → use native view/powershell directly." When a file is unindexed, the agent is trained to immediately inspect the raw filesystem.
2. Visual Inspection via token-goat map: Running token-goat map --compact prints the complete tree of indexed files. If a file is absent from the map, it is unindexed.
3. Integrity Check via token-goat doctor: Running token-goat doctor prints: "Symbols: X symbol(s) across Y indexed file(s)" and flags any unindexed files that match supported source extensions.

In src/cli_doctor_index.ts, checkParserFreshness queries SQLite using PARSER_FINGERPRINT (a hash computed from all AST parsing rules in src/parser.ts). If tree-sitter extraction logic changes in a release, the doctor check flags the mismatch:

The team does not need to constantly reindex manually for day-to-day coding. The background worker daemon (src/worker.ts) continuously monitors the project's dirty file queue:

• Whenever a developer edits, saves, or checks out a file, the worker immediately drains the queue and reparses that file using the running binary's active parser fingerprint.
• The only files that remain on the older parser version are untouched, dormant legacy files that have not been modified since the upgrade.

To guarantee complete freshness across the entire engineering organization:

1. Automated Upgrade Script: In enterprise developer setups/dotfiles, package upgrades are standardized:

   npm update -g token-goat && token-goat index

   Because token-goat index skips unchanged files matching the active fingerprint, reindexing an already-current repository takes only 2 to 4 seconds.
2. Pre-Push / Git Hook Integration: A simple git hook or weekly developer check can execute token-goat doctor to catch stale repositories before feature branches are submitted for PR review.

In src/constants.ts, dataDirForHome() defines the database path:

• Windows: C:\Users\<User>\AppData\Local\dfk-helper\token-goat\global.db
• macOS: ~/Library/Application Support/token-goat/global.db
• Linux: ~/.local/share/token-goat/global.db

OneDrive Directory Isolation on Windows: In Windows 11 Enterprise environments, OneDrive Known Folder Move (KFM) redirects and backs up only Desktop, Documents, and Pictures. Microsoft Group Policy and enterprise configurations explicitly exclude AppData\Local from OneDrive synchronization. The SQLite database is never synced to personal or corporate OneDrive cloud storage.

Is the SQLite database exposed to other users or processes on the workstation?

• POSIX (macOS/Linux): ensureDataDirPrivate() creates directory paths with mode 0700 (owner read/write/execute only) and files with mode 0600 (owner read/write only).
• Windows (NTFS): The directory inherits Windows user SID Access Control Lists (ACLs). Only the authenticated developer and local Administrator accounts have read/write access. Other local standard user accounts cannot read the database.

Which repositories are in scope, and who authorizes storage?

1. Restricted Repository Blacklisting: If a repository contains PCI-DSS payment code, secret cryptographic material, or highly classified IP that must never touch a machine-wide database, exclude it in global configuration:

   [worker]
   blocked_roots = ["C:/Projects/pci-payment-gateway", "C:/Projects/hr-pii-service"]

   Token-goat will completely refuse to index, parse, or cache files from those root directories.
2. Data Classification Sign-Off: Enterprise Information Security signs off under the corporate Workstation Endpoint Security Standard. Because developer laptops are protected by corporate BitLocker full-disk encryption, local SQLite indexing carries the identical security profile to Roslyn compiler caches, Visual Studio IntelliSense databases, and JetBrains IDE caches, which all store raw source ASTs in %LOCALAPPDATA%.

In src/embed_model.ts, model acquisition is not an arbitrary download. The model is hardcoded to revision ea104dacec62c0de699686887e3f920caeb4f3e3 of Xenova/bge-small-en-v1.5 with cryptographic hashes verified before use:

When ensureModelFiles() executes, it checks if the local file exists and runs sha256Of(target) === file.sha256. If the hash matches, it skips network requests entirely.

Security & Governance Architect's proposal is the exact gold standard for enterprise air-gapped deployments:

1. DevOps Provisioning: During standard developer machine image creation (or via internal Artifactory bundle download), copy the 2 verified files into:
   %LOCALAPPDATA%\dfk-helper\token-goat\models\Xenova\bge-small-en-v1.5\ea104dacec62c0de699686887e3f920caeb4f3e3\
2. Lock Down Configuration: Distribute corporate baseline token-goat.toml with:

   [network]
   offline = true

3. Zero Feature Loss: Because the files are pre-seeded and SHA-256 verified, semantic vector search, code embeddings, and OCR operate at 100% full capacity while network egress is completely blocked.

To verify the pre-seeded installation, run:

$ token-goat doctor
Embeddings: available
Security network: offline mode is on (network.offline)

Both checks pass with green status, confirming full local capability with zero network leakage.

The package implements strict supply-chain controls in .github/workflows/publish.yml:

• Ancestry Verification on Release: Releases can only be published from GitHub Actions CI. The release job executes git merge-base --is-ancestor "$GITHUB_SHA" origin/main to mathematically prove the release commit exists on main, preventing untracked feature branches or hijacked tags from publishing.
• Full Commit SHA Pinning: Every third-party GitHub Action (e.g. actions/checkout@3d3c42...) is pinned to an immutable 40-character commit SHA rather than mutable tags like @v4. This invariant is actively guarded by automated test tests/guards/ci_action_pins.test.ts.
• Cryptographic npm Provenance: Published via Sigstore with id-token: write, establishing a public, tamper-proof cryptographic attestation linking the npm tarball directly to the GitHub repository commit and workflow run.

Trusting version numbers (e.g. npm i token-goat@2.9.10) is vulnerable to upstream DNS or registry spoofing. The enterprise intake pipeline should verify Sigstore cryptographic provenance:

$ npm audit signatures
found 0 cryptographic signature vulnerabilities
Verified provenance for token-goat@2.9.10 (built by GitHub Actions commit 78e1af1... on main)

This confirms that the exact bits in the tarball were compiled directly by GitHub Actions from reviewed source on main with zero unauthorized tampering.

Once verified, the enterprise package intake pipeline should:

1. Mirror the verified tarball and its exact SHA-512 integrity hash into internal Artifactory (artifactory.enterprise.internal).
2. Lock developer machines to the internal mirror, completely preventing arbitrary public npm package fetching.

Token-goat is an external context governor, not a language runtime or framework. If harness vendors (Anthropic, GitHub, OpenAI) implement native context pruning, or if the organization decides to deprecate the tool, exiting is instantaneous:

$ token-goat uninstall --all --purge
Removed Claude Code hooks and shims
Removed Copilot CLI integration
Removed Codex CLI integration
Removed VS Code MCP registration
Removed delimited guidance blocks from CLAUDE.md and AGENTS.md
Purged ~/.local/share/token-goat (databases, models, and cache deleted)

Every configuration file modified by token-goat is backed up with timestamped copies (.bak.<timestamp>) during install, ensuring clean rollback without risk of corrupted developer settings.

What happens if upstream development ceases?

• Self-Contained Clean Architecture: The entire codebase is standard, modern TypeScript bundled with esbuild, with an extensive 1,000+ test suite running under Vitest.
• Internal Fork Viability: Because there are no proprietary cloud backends or external SaaS services, Enterprise Platform Engineering can fork the repository into internal GitLab/GitHub in under 1 hour and maintain it with zero external dependencies.

Corporate governance roles:

• Upgrade & Intake Owner: Enterprise AI Platform Engineering tests and approves all new releases before publishing them to the internal Artifactory repository. Developers never pull floating unvetted versions.
• Incident Response Plan: If an upstream release is flagged as vulnerable or compromised:
  1. Security Operations revokes the package from Artifactory within minutes.
  2. Centralized endpoint management (SCCM / Endpoint Central) executes token-goat uninstall --all --purge across corporate workstations, cleanly removing all hooks and shims with zero downtime.

The URL https://artifactory.enterprise.internal/feeds/npm/token-goat/versions points to the enterprise internal Artifactory repository. A (403) Unauthorized Request response is triggered by two specific conditions:

1. Missing or Expired npm Token: Your local ~/.npmrc does not contain an active bearer token for the artifactory.enterprise.internal host, or your corporate SSO session has timed out.
2. Remote Repository Mirror Restriction: Artifactory is configured with remote proxy caching rules that block anonymous fetching of external npm packages that have not been explicitly approved or whitelisted by DevOps.

To restore authenticated access in your local terminal:

1. Authenticate via npm command line using your corporate credentials:

   $ npm login --registry=https://artifactory.enterprise.internal/feeds/npm/

2. Or log into the internal Artifactory web UI, navigate to User Profile > Generate API Key / Identity Token, and append it to your ~/.npmrc:

   //artifactory.enterprise.internal/feeds/npm/:_authToken=AKCPxxxxxxxxxxxx

If authentication is valid but Artifactory continues to return 403:

The package token-goat has not yet been registered in the Artifactory remote mirror whitelist. Submit a standard Enterprise IT/DevOps service request: "Requesting npm proxy whitelist approval for package: token-goat on feed: artifactory.enterprise.internal".

Platform Engineer's goal—preventing tools from interfering with local coding projects—is a valid requirement. However, compiling a standalone native binary is unnecessary because token-goat already provides complete project isolation out of the box:

• External System Utility: Running npm install -g token-goat places the CLI into global user storage (e.g. %APPDATA%\npm on Windows, /usr/local/bin on POSIX). It acts as an external utility, exactly like git.exe, curl.exe, or rg.exe.
• Zero Local Repo Contamination: It never touches your local project's package.json, never injects local node_modules/, and creates zero dependencies in your C#, Python, Go, or Java repositories.
• Zero Missing Prerequisites: Token-goat exists exclusively as a companion to AI agents (Claude Code, GitHub Copilot CLI). Both of these agent harnesses are Node.js applications that already require Node.js 20+ on the developer workstation. No developer capable of running the agent is missing Node.

While bundling into a single token-goat.exe is technically possible via Node.js Single Executable Application (SEA) or Bun compile, doing so in an enterprise environment introduces serious operational friction:

• Native C-Addon Extraction: Token-goat relies on compiled native bindings: SQLite (better-sqlite3) and Tree-sitter parsers. Single-binary packagers cannot execute dynamic .node C DLLs directly from inside the binary image; they must unpack them into %TEMP% or AppData\Local\Temp at startup.
• Corporate EDR & Antivirus Interference: Enterprise Endpoint Detection and Response tools (CrowdStrike Falcon, Microsoft Defender for Endpoint) aggressively monitor the temp directory. Unsigned binaries dropping and executing executable DLLs from %TEMP% routinely trigger heuristic blocks, quarantined files, and intermittent crash loops.
• Code-Signing & SmartScreen Tax: Shipping an enterprise token-goat.exe requires maintaining internal Extended Validation (EV) code-signing pipelines to prevent Windows Defender SmartScreen from blocking untrusted execution on developer laptops.
• Upgrade Overhead: npm provides standardized, automated versioning (npm update -g token-goat). Custom binaries force the team to invent and maintain custom updater scripts and patch distribution mechanisms.

The standard, reliable path for enterprise engineering is to treat token-goat as a standard global npm utility:

1. Mirror the npm Package: Proxy the public npm package through the enterprise internal Artifactory repository (artifactory.enterprise.internal/feeds/npm/).
2. Standard Global Install: Developers install once via npm install -g token-goat, leveraging their existing workstation Node runtime with zero project interference.
3. Reserve Binaries as an Absolute Last Resort: Only invest in standalone native binary compilation if corporate governance strictly mandates developer machines with no Node.js runtime whatsoever.

In src/embed_model.ts, token-goat checks the local embedding model cache on startup. When an agent runs a semantic query, token-goat attempts to download Xenova/bge-small-en-v1.5 (~34 MB) from Hugging Face.

The Failure Loop: When corporate firewall proxy inspection blocks or intercepts the connection, it returns an HTML proxy block page or closes the socket. Token-goat verifies the SHA-256 checksum; because the download failed or returned HTML, the hash check fails. Token-goat immediately deletes the corrupt file (fs.rmSync(target)) to prevent crash loops. On the next prompt, it tries to download again, producing the repetitive prompt cycle.

To resolve this manually without needing external internet access:

1. Download the two pinned files from Hugging Face repository Xenova/bge-small-en-v1.5 (Commit revision ea104dacec62c0de699686887e3f920caeb4f3e3):
   • tokenizer.json (711 KB, SHA-256: d241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66)
   • onnx/model_quantized.onnx (34 MB, SHA-256: 6c9c6101a956d62dfb5e7190c538226c0c5bb9cb27b651234b6df063ee7dbfe4)
2. Place both files in your local token-goat model directory:
   Windows: C:\Users\<User>\AppData\Local\dfk-helper\token-goat\models\Xenova\bge-small-en-v1.5\ea104dacec62c0de699686887e3f920caeb4f3e3\
   Linux: ~/.local/share/token-goat/models/Xenova/bge-small-en-v1.5/ea104dacec62c0de699686887e3f920caeb4f3e3/
3. Verify by running:

   $ token-goat doctor
   Embeddings: available

If your team only uses surgical symbol reads (e.g. token-goat read "file::symbol") and test compression, you do not need local models at all! Disable embeddings in token-goat.toml:

[worker]
embed = false

With embed = false, token-goat will never attempt to download from Hugging Face, completely eliminating all download prompts while maintaining 100% of surgical read features.

Token-goat explicitly discloses this in its built-in documentation (token-goat stats --methodology):

This is by design.

Why doesn't token-goat run OpenAI's tiktoken or Anthropic's exact BPE tokenizer on every intercepted read?

• Runtime Hook Latency: Token-goat hooks already cost about 130 milliseconds per fire. Initializing and running a 100,000-vocabulary BPE tokenizer against a 2,000-line file would add 50 to 120 milliseconds of latency to every single file read and command execution.
• Harness & Model Agnosticism: An engineer may switch between several different model vendors in the same workday. Each model family uses a completely different tokenizer vocabulary. Computing model-specific tokens would require massive dependencies.
• The 4 Bytes/Token Proxy: In software engineering benchmarks across JavaScript, C#, Python, and JSON, character-to-token ratios consistently hover between 3.6 and 4.2 bytes per token. The bytes / 4 formula provides a remarkably accurate proxy at zero compute cost.

For engineers who want verifiable raw data without LLM tokenizer estimations:

• Full Details View: Run token-goat stats --full. This outputs exact bytes_saved alongside event counts and token estimates.
• Machine-Readable JSON: Run token-goat stats --json to extract raw integer byte counts per hook, file, and command:

  {
    "total_bytes_saved": 4821094,
    "total_tokens_saved": 1205274,
    "by_source": { "read": { "bytes_saved": 3912000, "events": 84 } }
  }

Platform Engineer's pragmatic observation captures the fundamental engineering tension in LLM agent design:

In a multi-turn task (5+ turns), surgical reads win decisively on total clock time because you avoid cumulative TTFT attention penalties on every turn.

Why is Platform Engineer noticing high slowness specifically in Luna queries?

• Model Architecture Difference: Larger frontier models tend to have stronger spatial reasoning and execute decisive lookups in 1 turn (e.g. token-goat read "src/auth.ts::loginUser").
• Exploratory Churn in Smaller Models: Lightweight, fast models generate text quickly but often lack architectural precision. A model like the one you're calling Luna may execute:
  semantic "login" → Wait for tool return → symbol loginUser → Wait for tool return → read "src/auth.ts::loginUser".
• Each tool call requires an API roundtrip (HTTP request → inference → response → local execution → return HTTP request). Even though each tool execution takes only 5ms, 4 sequential API roundtrips over corporate VPN add 4 to 8 seconds of pure network latency.

To prevent excessive roundtrips while preserving context benefits:

1. Small-File Exemption Gate: Files under ~200 lines are exempt from surgical interception. The agent reads the entire file natively in 1 shot without any multi-turn hunting.
2. Code Folding on First Read: In src/code_fold.ts, when an agent reads a large file for the first time, token-goat delivers a structural outline (class definitions, method signatures, docstrings, with long function bodies folded). This gives the model the entire file layout in a single tool turn!
3. Prompt Rule Enforcement: The prompt instructions explicitly instruct agents: "Know the symbol name? Use symbol <name> directly instead of wandering through semantic search."

Platform Engineer's question hits a common developer intuition: if small, fast models cost pennies per million tokens and generate output fast, why should anyone care about trimming files?

The answer has very little to do with token pricing and everything to do with output correctness:

• Small Models Are More Sensitive to Bad Context, in General: Larger frontier models tend to tolerate irrelevant context better than smaller, faster ones. This project has not measured that difference directly, but it follows from the same context-degradation research cited in Q-11 (Liu et al., "Lost in the Middle"), which is not specific to any one model size.
• The Cost of a Hallucinated Patch: If a lightweight model reads a bloated 3,000-line file and hallucinates a non-existent method signature, the build fails. The agent then spins into a multi-turn retry loop trying to debug its own broken code, burning developer time. The "cheap" model can become expensive in human friction, independent of its token price.
• What Token-Goat Actually Measured: This project's own evaluation (see Q-11) is a cost comparison, not a quality comparison: a paired A/B test showing a 64.0% median billing-weighted token saving on the clean set. It used one frontier model on both arms and does not speak to how a smaller or faster model would behave; no task-completion-rate claim is made here for any model.

Cross-Platform Systems Engineer asks a concrete mathematical question: does token-goat carry Turn-1 overhead, and does it penalize single-turn ticket decomposition sessions on expensive models like Opus 5?

Token-goat injects concise routing instructions into the agent's prompt (via CLAUDE.md or Copilot CLI system prompt), consuming approximately 900 tokens. But does that make a single-turn ticket breakdown more expensive? No—in realistic enterprise workflows, it saves tens of thousands of tokens on Turn 1 alone.

Note on the isolated toy case: The only theoretical scenario where token-goat represents a net cost is pasting a tiny 150-word raw text snippet into an empty chat with zero external fetches, zero policy lookups, and zero repo grounding (net penalty: ~900 tokens, or ~$0.014 on Opus). But that is a generic chatbot chat, not an enterprise quality agent workflow. Though it would explain my own negative experiences with IT tickets.

Systems Engineer notes: "I am also noticing a lot of calls to token-goat semantic which are not free."

There is a critical misconception here: token-goat semantic is not a cost—it is one of the highest-leverage token reducers in the entire system.

Let's break down the exact economics across all three cost dimensions:

• Dollar / API Cost: $0.00 (Completely Free). token-goat semantic does not call OpenAI embeddings, Anthropic, or any paid cloud service. It runs 100% locally on your machine's CPU using ONNX Runtime (bge-small-en-v1.5) and queries local SQLite vector tables. It consumes zero cloud API tokens and costs $0.00.
• Token Savings: Returns a short ranked list of locations instead of a repository-wide text dump.
  When an agent wants to discover where a concept lives (e.g., "where is payment retry handled?"):
  • Without token-goat semantic: The agent executes recursive grep or findstr commands across the repo, which dumps every matched line whether or not it is relevant: searching this repository’s own src/ for retry returns 24,189 characters, roughly 6,000 tokens. Worse, if the match list does not reveal the context, the agent falls back to opening whole source files.
  • With token-goat semantic: The local ONNX vector search returns a ranked handful of hits, each named by file, symbol, and line range (e.g., src/billing/payment.ts:42 (retryPayment)) with its body—about 4,900 characters, roughly 1,200 tokens, measured on this repository.
  • Net Token Savings: Every call to semantic saves 1,500 to 10,000+ tokens by preventing the model from performing shotgun text searches or blind full-file reads!
• Execution Latency: 50 to 150 Milliseconds. Running locally on CPU, vector inference and SQLite cosine similarity take tens of milliseconds—orders of magnitude faster than an LLM network round-trip.

Why the Agent Calls It Frequently: The agent's system guidance explicitly instructs it to reach for token-goat semantic first to avoid context bloat. Every semantic call you see in the logs represents a massive 2,000+ token grep dump or 10,000-token blind file read that was successfully prevented.

Does using token-goat for single-turn ticket breakdown provide net savings on average? No dedicated evaluation of ticket-breakdown sessions specifically has been run, so no percentage or dollar figure is claimed here for that workflow. The general argument for why it should help follows from the same mechanism as Q-11's measured result.

The reason lies in how grounded a real ticket decomposition tends to be:

• Ungrounded Decompositions Are Risky: Asking a model to decompose an issue ticket without repo grounding invites hallucinated service boundaries or DTO contracts that do not match the codebase, and acceptance criteria that violate repo conventions.
• Real Architecting Is Inherently Grounded: In practice, a ticket decomposition typically needs several targeted context lookups: the linked ticket or spec, architectural standards, and existing domain interfaces or schemas.

The Bottom Line: Grounding a ticket breakdown requires reading real code either way; token-goat's surgical reads make each of those lookups cheaper than a whole-file read would be, for the same reason Q-11's paired evaluation measured a token saving on bug-fix tasks. No separate measurement exists yet for ticket-breakdown sessions specifically, and none is claimed.

If your team frequently decomposes issue tickets, interacts with custom MCP (Model Context Protocol) servers, or runs context-bloating CLI tools that dump thousands of lines of JSON, HTML, or logs into your agent sessions, we can optimize Token-Goat to filter and surgically slice those exact payloads.

To safely share the structural and context characteristics of your tickets without exposing proprietary logic, PII, or internal keys, run the following prompt with your local AI assistant to generate a 100% sanitized execution profile:

I want to share an execution trace of our typical ticket decomposition and MCP tooling workflow so the Token-Goat maintainer can build surgical filters for our specific toolchain.

Please analyze our recent session / ticket breakdown task and generate a sanitized workflow report adhering strictly to these rules:
1. REDACT ALL SENSITIVE DATA: Replace all proprietary code, internal URLs, project keys, company names, employee names, IPs, secrets, and customer data with dummy placeholders (e.g., [COMPANY], ISSUE-XXXX, [SERVICE_NAME], https://example.com/api).
2. MCP & TOOL INVENTORY: List all tools called during the session (e.g., Issue Tracker MCP, Confluence web fetch, database query, git log, file read) along with the estimated token/byte payload returned by each.
3. CONTEXT BOTTLENECK ANALYSIS: Identify which specific tool outputs dumped the largest volume of low-signal context into the prompt (e.g., raw JSON schemas, unfiltered HTML tables, repetitive system headers).
4. SURGICAL SPECIFICATION: Detail what minimal subset of that data the model actually required to fulfill the user story.

Output the result as a concise Markdown summary that contains zero proprietary information.

Share that sanitized output with us, and we will build targeted surgical filters (e.g., dedicated MCP output interceptors, JSON query extractors, or custom ticket parsers) directly into Token-Goat for your engineering workflow.

macOS is a first-class supported platform in token-goat with dedicated continuous integration testing. In .github/workflows/ci.yml, every single commit to main and every pull request runs the full test matrix across three operating systems:

The entire 1,000+ unit, integration, and guard test suite runs natively on macOS in GitHub Actions on every release.

Inside WSL2, token-goat operates as a standard Linux service targeting Node.js 22.16+:

• XDG Base Directory Compliance: Global databases and local models follow Linux XDG conventions (~/.local/share/token-goat/), secured with POSIX directory permissions (0700) and database file permissions (0600).
• POSIX Concurrency & WAL Locking: SQLite WAL mode (better-sqlite3) leverages Linux kernel fcntl file locks without the locking friction sometimes seen on remote network shares.
• CI Validation on Linux: Every commit is validated across Linux runners (ubuntu-latest) in .github/workflows/ci.yml across unit tests, guards, and built-bundle command matrix tiers.

Development in enterprise environments often straddles Windows and WSL. Token-goat handles cross-environment path mapping transparently:

• Universal WSL Path Regex (WSL_PATH_RE): In src/paths.ts and src/path_containment.ts, patterns matching /mnt/([a-zA-Z])/(.*) automatically map to normalized c:/... paths, ensuring consistent cache keys and index deduplication across both shells.
• WSL Interop Cat Interception: In src/bash_extractors.ts, extractWslCatFile intercepts proxied commands like wsl bash -c "cat /mnt/c/...", preventing whole-file dumps and offering surgical symbol/section alternatives.
• Path Pinning & Security Containment: In src/mcp_server.ts, both the raw WSL mount spelling and the normalized Windows spelling are pinned to eliminate directory traversal escapes while respecting configured root boundaries.

To maximize performance when using token-goat in WSL:

• Store Active Projects on Native ext4: Projects located inside the WSL filesystem (e.g., /home/user/projects/) benefit from native Linux ext4 filesystem speeds. Accessing projects across the Windows 9P mount bridge (/mnt/c/...) introduces cross-OS I/O overhead during initial cold indexing.
• Background Priority Scheduling: In src/process_priority.ts, worker indexing lowers process priority via native POSIX nice levels, ensuring background AST indexing never starves interactive developer shells.
• Windows Service Context Limitation: Automated background tasks running under Windows NT AUTHORITY\SYSTEM account cannot spawn wsl.exe directly (Microsoft limitation WSL_E_LOCAL_SYSTEM_NOT_SUPPORTED); interactive developer sessions and user tokens execute WSL without restriction.