savant-code 0.0.17 → 0.0.19

package/docs/Savant-Code Business And Backend Research.md

@@ -0,0 +1,222 @@
+<!-- markdownlint-disable MD041 -->
+
+> **Historical note:** This document was originally titled *FreeBuff Business And Backend Research* and uses the original product names (FreeBuff, Codebuff) because it cites external sources and research from that period. The product has since been rebranded to **Savant-Code / Savant-Free**. The file has been renamed to reflect the current branding; the original prose is preserved for historical accuracy.
+>
+> **Current-plan boundary:** The infrastructure, provider relationships, hosting, and partnership descriptions below are historical/external analysis, not commitments or claims about this project. The current strategy is to release Savant-Code first as a local/BYOK product, gain users, and only then evaluate, design, build, and operate our own backend for a future free product. We are not hosted by FreeBuff, are not partnered with FreeBuff, and do not depend on FreeBuff or another external hosting provider for that future backend.
+
+# **Strategic Architectural and Economic Analysis of Free-Tier AI CLI Coding Agents**
+
+## **Executive Summary**
+
+The rapid commoditization of large language models (LLMs) has catalyzed a fundamental restructuring of developer workflows, shifting the locus of autonomous code generation from web-based conversational interfaces to highly integrated, terminal-native environments. Codebuff, alongside its ad-supported counterpart FreeBuff, represents a sophisticated architectural iteration within this paradigm. By utilizing a multi-agent orchestration framework, the platform parses local directories, formulates architectural plans, executes precise file modifications, and performs autonomous code reviews directly within the developer's command-line interface. While the premium coding assistant market has coalesced around subscription models ranging from $20 to $200 per month, FreeBuff operates a zero-cost tier subsidized entirely by terminal-embedded text advertisements and strategic data-sharing partnerships with model providers1.  
+Developing a sustainable inference backend that guarantees zero-cost access to frontier models requires an exceptionally precise arbitrage engine. The architecture must dynamically balance the fluctuating costs of inference against the premium revenue yields generated by developer-focused ad networks, all while maintaining rigorous session control and mitigating abuse. A forensic analysis of the platform’s operations—encompassing its monetization engine, server-side proxy architecture, model provider unit economics, and client-side orchestration logic—reveals a highly optimized, stateful gateway. This report systematically deconstructs the operational mechanics of the api.savant-code.com backend infrastructure, the integration of networks like Gravity and ZeroClick, and the precise economic thresholds required to serve free artificial intelligence coding inference at scale.
+
+## **The Economics of Terminal-Embedded Advertisements**
+
+### **Monetization Topography in the Command Line**
+
+Monetizing a Command Line Interface (CLI) introduces distinct structural and behavioral challenges. Unlike traditional web properties or integrated development environments (IDEs) equipped with DOM-based rendering engines, a CLI lacks the capacity to serve rich media, video, or standard IAB banner formats. Consequently, platforms like FreeBuff must integrate specialized, AI-native text ad networks directly into their rendering loops. The system leverages an OpenTUI framework—a custom React-based terminal rendering engine that allows for seamless, flicker-free text updates and mouse interactions—to serve contextual advertisements without disrupting the developer's primary workflow4.  
+The platform’s advertising stack aggregates demand from networks specifically engineered for high-intent technical audiences and generative AI surfaces, primarily Gravity, ZeroClick, and Carbon Ads1. ZeroClick operates an application programming interface (API) and ad marketplace designed explicitly for AI products, monetizing on a Cost-Per-Click (CPC) and Cost-Per-Mille (CPM) basis by matching brand bids to contextual user intent within AI-driven answers5. By entirely avoiding third-party cookies, ZeroClick complies with GDPR requirements and bypasses traditional ad-blocking extensions, which are utilized by more than fifty percent of the global developer demographic5.  
+Gravity provides a similar infrastructure, enabling AI applications to monetize conversational latency by injecting native sponsored suggestions into waiting rooms and terminal outputs6. The FreeBuff architecture explicitly leverages a waiting\_room surface to serve these Gravity ads. Client-side integration logic, utilizing hooks such as use-gravity-ad and lazy-response-ads, pulls localized text payloads from the upstream /api/v1/ads endpoint1. These payloads are rotated on a strict thirty-second interval, and impressions are logged back to the server via the /api/v1/ads/impression tracking endpoint8.
+
+### **Yield Analysis: CLI Impressions Versus Traditional Display**
+
+The revenue potential of a CLI-embedded text ad diverges significantly from traditional display advertising. Carbon Ads, a dominant player in the developer advertising ecosystem, typically yields a publisher CPM ranging from $0.50 to $1.10 for standard run-of-network display across its ecosystem of design and development blogs9. However, highly targeted programmatic advertising aimed at developers commands significantly higher premiums due to the audience's purchasing power and technical decision-making authority.  
+For in-IDE or highly contextual developer environments, effective CPMs escalate dramatically. Industry benchmarks indicate that general developer sites yield CPMs between $5.00 and $15.00, niche technical publications reach $15.00 to $35.00, and highly engaged, in-IDE advertising networks can sustain CPMs ranging from $20.00 to $45.0011. In a CLI coding tool, the developer's attention is entirely focused on the terminal output while waiting for the LLM to complete its contextual mapping and code generation. This captive attention during latency windows translates to high engagement rates, allowing the platform to command premium rates.
+
+| Ad Network / Environment | Estimated CPM Range | Primary Targeting Mechanism | Placement Mechanics |
+| :---- | :---- | :---- | :---- |
+| Carbon Ads (Standard Web) | $0.50 \- $1.10 | Contextual (Site Category) | Sidebar / Header Display9 |
+| General Developer Web | $5.00 \- $15.00 | Topic / Keyword | In-feed / Banner11 |
+| In-IDE / Terminal Ads | $20.00 \- $45.00 | Contextual Intent / Action | CLI Waiting Room / Prompt Header11 |
+| ZeroClick (AI Native) | Variable (Guaranteed Min) | Real-time Intent Parsing | Dynamic Text Generation5 |
+
+### **Unit Economics and Profitability Thresholds**
+
+To evaluate the long-term sustainability of the ad-supported model, the revenue generated per session must be juxtaposed against the token burn rate. A typical autonomous coding request involves substantial context gathering; the CLI utilizes tree-sitter to parse the local directory, generating a comprehensive abstract syntax tree that is subsequently injected into the model's context window13.  
+If an average multi-agent refactoring task consumes roughly 150,000 input tokens and generates 2,000 output tokens, the raw inference cost depends entirely on the selected model. FreeBuff defaults to highly efficient models such as DeepSeek V4 Flash and Gemini 3.1 Flash Lite for its free tier1. Assuming a blended rate of $0.14 per million input tokens and $0.28 per million output tokens, a single task incurs an inference cost of approximately $0.0215.  
+Conversely, the ad revenue generated during this process depends on the duration of the latency window and the rotation frequency of the ads. With the OpenTUI interface rotating Gravity ads every thirty seconds during the waiting\_room phase, a task that takes two minutes to execute will generate four ad impressions4. If the platform commands a conservative developer CPM of $15.00 ($0.015 per impression), four impressions yield $0.06 in gross revenue.
+
+| Economic Metric | Estimated Value | Calculation Framework |
+| :---- | :---- | :---- |
+| Inference Cost (DeepSeek Flash) | $0.0215 | (150K / 1M) \* $0.14 \+ (2K / 1M) \* $0.28 |
+| Ad Impressions per Task | 4 Impressions | 2-minute execution with 30s rotation8 |
+| Ad Revenue per Task | $0.0600 | Assuming $15.00 CPM ($0.015 per impression) |
+| **Gross Margin per Task** | **64.1%** | ($0.0600 \- $0.0215) / $0.0600 |
+
+While this demonstrates theoretical profitability, the margins are razor-thin and highly sensitive to API pricing fluctuations and ad-blocker circumvention. To ensure users cannot simply disable the ad rendering logic in the open-source CLI to siphon free inference, the backend enforces a mandatory "Ad Chain \+ Streak" validation. The server requires cryptographic proof that the client has successfully completed the ad flow and logged the impressions before provisioning the WebSocket connection for the subsequent inference session8.
+
+## **Server-Side Proxy Architecture and Routing Mechanics**
+
+### **The Stateless API Gateway**
+
+The operational core of the platform relies on a cloud-routed architecture where the local CLI acts solely as a telemetry gatherer, UI renderer, and execution sandbox, while all heavy processing and API key management occurs server-side. The production backend, originally located at api.savant-code.com and later migrated to codebuff.com and freebuff.com, functions as a highly scalable, stateless proxy13.  
+By centralizing the API keys for OpenRouter, OpenAI, Anthropic, and native providers on the server, the architecture inherently prevents credential scraping. The proxy utilizes WebSockets to establish a persistent, bidirectional stream between the developer's local machine and the selected model provider, minimizing handshake latency during iterative agent loops13.  
+The client authentication flow is designed to securely bridge the terminal and the web. Upon initial execution, the CLI prompts the user to authenticate via a browser-based GitHub OAuth flow16. The freebuff/web/src/app/api/auth/cli/code/route.ts endpoint manages the callback, issuing an authentication token that the CLI subsequently polls and stores locally at \~/.config/manicode/credentials.json (or the Windows equivalent)14. During execution, hooks such as use-auth-query.ts seed the local SDK cache with these credentials, and the token is validated against the /api/v1/me endpoint to authorize access14.
+
+### **Session Validation and Waiting Room Logic**
+
+Because aggregate inference costs can compound exponentially during peak usage, the backend implements a rigorous queuing and session management system. The primary entry point for free-tier users is the /api/v1/savant-free/session endpoint, which governs the lifecycle of every developer interaction17.  
+The architecture segments sessions into distinct, strictly enforced state machines:
+
+* **Active**: The backend has provisioned the session, allocated upstream API bandwidth, and granted the user a dedicated lock on a specific model.  
+* **Queued**: The user is placed in a virtual waiting room due to global rate limits or upstream capacity constraints. The CLI continuously polls the backend until the state transitions to active. A shimmer animation in the CLI visually communicates this waiting state, though recent commits in the repository indicate efforts to remove or optimize this animation to reduce perceived latency8.  
+* **Ended**: The session has naturally expired based on time constraints or token expenditure limits, requiring the client to request a new allocation.  
+* **Superseded**: The session was overwritten by a newer context window, typically when a user initiates a new chat thread or resets the workspace.  
+* **Disabled**: The user is operating within a paid tier, utilizing the pay-as-you-go credit system, or utilizing a Bring-Your-Own-Key (BYOK) configuration, thereby bypassing the free-tier queue logic entirely8.
+
+### **Rate Limiting and Geographic Tiering**
+
+To maximize the economic viability of the free tier, the backend enforces complex geographic and model-specific rate limiting. The system detects the user's geographic origin via IP address and segments access into two distinct tiers: "Full mode" and "Limited mode."  
+Full mode is restricted to approximately twenty-five countries (including the US, Canada, UK, and select EU nations) that typically offer the highest ad CPM yields1. Users in these regions are granted access to premium models such as DeepSeek V4 Pro, MiMo 2.5 Pro, and MiniMax M3. Conversely, Limited mode acts as a global fallback, automatically applied to users in non-premium regions or those attempting to mask their location via VPNs. Limited mode restricts the user to highly efficient, lower-cost models like DeepSeek V4 Flash and enforces a strict cap of six one-hour sessions per day1.  
+Furthermore, the backend implements model-specific throttles. For instance, repository actions reveal that GLM (Zhipu) sessions are explicitly rate-limited to five sessions per twenty-hour window, preventing excessive API expenditure on a single provider20. If a Limited tier user attempts to request a Full tier model, the backend rejects the payload with a session\_model\_mismatch error. If a user attempts to rapidly switch models while an existing session is actively utilizing an upstream connection, the proxy throws a model\_locked error, requiring the CLI to gracefully terminate the prior session before requesting the new model8.
+
+### **Combating Proxy Exploitation and Abuse**
+
+The fundamental vulnerability of a free, stateless API gateway is the threat of reverse-engineering. Independent developers routinely construct unauthorized proxy servers designed to siphon free inference by mimicking the official client. Analysis of reverse-engineered repositories, such as Freebuff2API and free-buff-lol, provides a comprehensive view of the evasion techniques utilized to exploit the backend8.  
+These unauthorized proxies translate standard OpenAI API requests (e.g., /v1/chat/completions) into the proprietary FreeBuff backend format, allowing users to route free inference into automated scripts, competing IDEs, or discord bots22. The proxies deploy sophisticated countermeasures to bypass the backend's WAF and rate limiters. They inject HAR-style browser-compatible headers (Accept-Encoding, Connection, Host) to spoof organic terminal traffic, and they strip the cost\_mode field from the JSON payload to bypass CLI-only validation checks8.  
+To circumvent the six-session geographic limit, these proxies automatically route Limited-tier requests through Cloudflare WARP SOCKS5 proxies8. To bypass per-account limits, they pool arrays of GitHub OAuth tokens, rotating them on a configurable round-robin interval (e.g., every six hours)15.  
+In response to this adversarial environment, the backend architecture must continuously evolve. The server implements a global request debounce mechanism, requiring a minimum 1.3-second gap between requests to prevent rapid token scraping8. More critically, the server validates agent definitions prior to authorizing chat requests and strictly enforces the aforementioned ad chain validation8. If an incoming request perfectly mimics the CLI fingerprint but fails to register upstream hits on the /api/v1/ads/impression endpoint, the backend algorithms categorize the traffic as anomalous and issue an account ban8.
+
+## **Provider Economics and the "Data for Compute" Trade-off**
+
+The financial architecture required to serve free inference to an escalating user base—estimated at over 170,000 registered users with peak loads of 1,300 concurrent sessions—relies heavily on strategic alliances with specific LLM providers23. The platform explicitly integrates models from DeepSeek, Moonshot (Kimi), MiniMax, and Zhipu (GLM), bypassing traditional Western frontier models like Anthropic's Claude or OpenAI's GPT-4 for the free tier1.
+
+### **The Mechanics of Data Subsidization**
+
+The economic feasibility of this model is anchored in a controversial but highly effective "data for compute" exchange. The official documentation features a prominent caveat: models or features labeled "May use data for AI training" will utilize user submissions for product improvement1. This includes raw prompts, chat messages, pasted content, repository structure, and the complex, multi-turn reasoning traces generated by the autonomous agents.  
+Providers such as DeepSeek and MiniMax absorb the overwhelming majority of the computational costs required to serve the API requests in exchange for this proprietary telemetry8. For foundational model developers, acquiring authentic, highly complex software engineering workflows—complete with errors, iterative debugging, and successful resolution paths—is vastly more expensive and time-consuming than synthesizing raw compute power. By channeling millions of developer interactions through these specific endpoints, the platform acts as a massive, decentralized data broker. The developers trade their localized code context and privacy for zero-cost automation, while the model providers receive the precise dataset required to train the next generation of reasoning models.
+
+| Model Provider | Core Model | Platform Tier | Data Privacy Posture |
+| :---- | :---- | :---- | :---- |
+| DeepSeek | V4 Pro | Full Mode | Collects telemetry for training8 |
+| DeepSeek | V4 Flash | Limited Mode | Collects telemetry for training8 |
+| MiniMax | M3 | Full Mode | Collects telemetry for training8 |
+| Moonshot | Kimi K2.7 Code | Full Mode | Variable (subject to provider terms)1 |
+| Google | Gemini 3.1 Flash | Background/File Research | Variable (subject to Google terms)1 |
+
+### **Projecting the Monthly Inference Liability**
+
+To contextualize the scale of this operation, one must model the aggregate token expenditure. With 1,300 concurrent users at peak load, the throughput demands are intense. Assuming that 20% of concurrent users are actively initiating an agent loop at any given minute, the backend processes roughly 260 complex requests per minute.  
+Due to the platform's multi-agent orchestration, a single user prompt invokes multiple distinct API calls. The File Picker Agent scans the directory, the Planner Agent drafts the implementation, the Editor Agent executes the modifications, and the Reviewer Agent validates the output1. This parallel fan-out architecture multiplies token consumption. If an average combined interaction consumes 150,000 input tokens and 5,000 output tokens, the system processes approximately 39 million input tokens and 1.3 million output tokens per minute.  
+Over a standard twenty-four-hour period, this equates to roughly 56 billion input tokens and 1.8 billion output tokens. If the platform were forced to pay standard commercial rates for a frontier model (e.g., $3.00 per million input tokens), the daily API liability would exceed $168,000. However, by routing this traffic to heavily subsidized, open-weight models offering rates closer to $0.14 per million input tokens, the gross daily expenditure is compressed to approximately $7,840. When this severely reduced baseline is offset by the revenue generated from CLI ad impressions, the operational deficit is transformed into a sustainable, and potentially profitable, unit economic model.
+
+## **Codebase Architecture and Client-Side Orchestration**
+
+An analysis of the CodebuffAI/codebuff open-source repository exposes a highly modular, TypeScript-based monorepo designed to facilitate rapid feature deployment and seamless cross-platform execution. The repository is partitioned into logical workspaces, most notably cli, sdk, web, common, agents, and packages1.
+
+### **Monorepo Structure and Backend Routing**
+
+The integration between the CLI and the backend is deeply intertwined within the repository's configuration files. The common/src/env.ts module establishes the environmental baseline, explicitly routing traffic to www.codebuff.com to prevent HTTP 301 redirects from stripping the critical Authorization headers required for session validation14.  
+The backend components are nested within the freebuff/web/src/app/api/ directory. This structure houses the critical routing infrastructure, including the /auth/cli/code/route.ts endpoint for managing OAuth handshakes, the /healthz/route.ts endpoint for CLI connection polling, and the user validation logic14. By co-locating the CLI logic and the Next.js backend routing within a single repository, the development team maintains strict type safety across the entire network boundary.
+
+### **Multi-Agent Execution Graph**
+
+The agents directory encapsulates the discrete logic for the sub-agent ecosystem. The platform departs from the traditional approach of relying on a single, monolithic system prompt to handle all logic. Instead, it coordinates specialized agents through a directed acyclic graph (DAG) of tasks, executing via a TypeScript-based programmatic control loop that allows agents to spawn subagents, branch on conditions, and execute terminal commands natively1.  
+When a developer requests a complex refactoring, the orchestrator simultaneously spawns multiple Editor Agents in parallel. Each agent utilizes the same prompt cache but applies a slightly different implementation strategy or inference temperature. A dedicated Selector Agent evaluates the parallel outputs, merging optimal code blocks and discarding hallucinations. The resulting artifact is then passed to a Reviewer Agent, which automatically executes local tests and linters in the background, utilizing the sandbox execution environment to prevent malicious code from compromising the host machine4.  
+This parallel execution model drastically reduces wall-clock time. By trading higher total token consumption—which, as established, is economically negligible due to provider subsidies—for significantly lower latency, the platform routinely achieves a 5x to 10x speedup compared to serialized agents, completing complex features in minutes rather than hours1.
+
+### **Ad Integration and Rendering Logic**
+
+The advertising subsystem is surgically embedded into the CLI's OpenTUI rendering loop. The architecture ensures that ad fetching operations are strictly asynchronous, preventing network latency from blocking the main terminal interaction thread.  
+The client-side implementation leverages custom React hooks. The use-gravity-ad hook interfaces with the backend /api/v1/ads endpoint, pulling the text payload and injecting it into the waiting\_room component while the LLM processes the request8. To ensure compliance with ad network visibility standards, the CLI monitors the active state of the terminal. The lazy-response-ads integration guarantees that impressions are only logged when the terminal maintains focus and the ad remains visible for the requisite duration. Once validated, the CLI fires the confirmation payload to the backend, securing the ongoing inference session1.
+
+## **Competitive Landscape and Market Positioning**
+
+The autonomous coding agent sector is fiercely contested, dominated by heavily capitalized startups and incumbent tech giants. The primary competitive matrix pits FreeBuff against subscription-based terminal agents like Anthropic's Claude Code, full-scale agentic IDEs like Cursor and Windsurf, and emerging ecosystem products like Google's Antigravity CLI1.
+
+### **The Subscription vs. Ad-Supported Dichotomy**
+
+The current market standard for premium AI assistance relies on flat-rate subscriptions, typically demanding $20 per month for basic access and up to $200 per month for maximum utilization tiers2. Products like Claude Code justify this expense by providing unfiltered access to frontier models (Claude 3.5 Sonnet) combined with stringent enterprise privacy guarantees—expressly prohibiting the use of customer data for model training.  
+FreeBuff bypasses this premium segment, targeting the massive demographic of price-sensitive developers, students, and open-source contributors. By offering absolute feature parity—including file mentions, bash execution, generic subagent delegation, and built-in browser automation—for zero financial cost, the platform rapidly accelerates user acquisition1. Furthermore, the platform acts as an agnostic aggregator. While Claude Code enforces strict vendor lock-in to Anthropic's models, the underlying Codebuff SDK supports arbitrary model routing via OpenRouter, allowing users to hot-swap models based on specific task requirements1.
+
+### **The Threat of Agent-First IDEs**
+
+Google's Antigravity IDE and platforms like Cursor represent a distinct strategic threat. These platforms integrate the agent directly into the text editor, leveraging deep, multi-surface orchestration to control the editor, terminal, and browser simultaneously27. Antigravity, for instance, utilizes a lightweight Terminal Sandbox (nsjail on Linux, sandbox-exec on macOS) to execute terminal commands autonomously while protecting the host system from unauthorized outbound requests28.  
+To counter this, FreeBuff emphasizes the minimal friction of a terminal-native posture. The platform argues that senior developers prefer to augment their existing, highly customized environments (Neovim, Tmux, IntelliJ) rather than migrating to an entirely new, opinionated IDE framework1. By running directly in the shell alongside standard Unix utilities, the agent integrates seamlessly into existing continuous integration (CI) workflows.
+
+## **Synthesized Conclusions and Architectural Directives**
+
+The architecture of FreeBuff demonstrates that providing free, autonomous AI coding assistance is economically viable at scale, provided the system rigorously balances ad monetization against heavily subsidized inference costs. For organizations seeking to construct a competing, sustainable inference backend, the following architectural directives are paramount:
+
+> 1. **Cryptographic Impression Tracking**: Traditional API callbacks for ad impressions are insufficient in a
+>    developer-centric environment prone to reverse-engineering. The backend must implement a cryptographic handshake
+>    wherein the ad payload contains a unique, time-sensitive nonce. The CLI must execute a localized proof-of-work
+>    or visual hashing function on the rendered ad text, returning the computed signature to the backend. This
+>    strictly couples inference provisioning to verified ad consumption, neutralizing headless API proxies like
+>    Freebuff2API.
+> 2. **Dynamic Data-for-Compute Routing**: Abstract the model provider layer entirely. The sustainability of the
+>    free tier relies entirely on open-weight providers prioritizing data acquisition over API revenue. Build a
+>    dynamic routing engine that monitors the real-time cost of inference across various providers. If a specific
+>    provider withdraws their data-sharing subsidy or alters their terms of service, the router must seamlessly fall
+>    back to the next most efficient model without disrupting the user's workflow.
+> 3. **Aggressive Context Pruning via Local Embeddings**: Transmitting comprehensive abstract syntax trees for
+>    every interaction incurs massive token costs. Implement a local semantic indexer within the CLI prior to
+>    transmission. The local agent should utilize lightweight, locally hosted embedding models (e.g.,
+>    all-MiniLM-L6-v2) to prune irrelevant files, sending only the most statistically significant code chunks to the
+>    proxy server. This reduces upstream token expenditure and drastically improves response latency.
+> 4. **Asynchronous Parallel Orchestration**: Adopt the multi-agent DAG model for all complex reasoning tasks.
+>    User retention is highly correlated with perceived speed. Utilizing highly efficient models like DeepSeek Flash
+>    to run three parallel implementations alongside a dedicated Selector Agent will consistently outperform a
+>    single, expensive frontier model in both latency and overall cost-efficiency.
+
+By synthesizing terminal-native ad integration with aggressive provider subsidies and multi-agent parallelization, the architecture surrounding platforms like FreeBuff establishes a highly defensible, economically scalable blueprint for the future of developer tooling.
+
+### **Works cited**
+
+> 1. CodebuffAI/codebuff: Generate code from the terminal\! \- GitHub,
+>    [https://github.com/CodebuffAI/codebuff](https://github.com/CodebuffAI/codebuff)
+> 2. The free alternative to Claude Code | Freebuff,
+>    [https://freebuff.com/blog/free-claude-code-cli-coding-agent-alternative-freebuff](https://freebuff.com/blog/free-claude-code-cli-coding-agent-alternative-freebuff)
+> 3. The free alternative to Antigravity CLI | Freebuff,
+>    [https://freebuff.com/blog/free-antigravity-cli-coding-agent-alternative-freebuff](https://freebuff.com/blog/free-antigravity-cli-coding-agent-alternative-freebuff)
+> 4. tips | Codebuff Docs,
+>    [https://www.codebuff.com/docs/tips/what-makes-codebuff-unique](https://www.codebuff.com/docs/tips/what-makes-codebuff-unique)
+> 5. Zeroclick, [https://info.zeroclick.ai/](https://info.zeroclick.ai/)  
+> 6. Gravity | The Ad Network for AI, [https://www.trygravity.ai/](https://www.trygravity.ai/)  
+> 7. Developer Marketing Platforms Compared: Choosing Your Channel Mix for 2026,
+>    [https://business.daily.dev/resources/developer-marketing-platforms-comparison-channel-mix/](https://business.daily.dev/resources/developer-marketing-platforms-comparison-channel-mix/)
+> 8. notBlubbll/free-buff-lol \- GitHub,
+>    [https://github.com/notBlubbll/free-buff-lol](https://github.com/notBlubbll/free-buff-lol)
+> 9. Frequently Asked Questions | Carbon Ads, [https://www.carbonads.net/faq](https://www.carbonads.net/faq)  
+> 10. Carbon Ads • OSS.Fund | Open Source Sustainability Directory,
+>    [https://www.oss.fund/carbon-ads/](https://www.oss.fund/carbon-ads/)
+> 11. CPM, CPC, CPA: Which Pricing Model for Developer Advertising? | Idlen,
+>    [https://www.idlen.io/blog/cpm-cpc-cpa-developer-advertising-pricing-guide/](https://www.idlen.io/blog/cpm-cpc-cpa-developer-advertising-pricing-guide/)
+> 12. Idlen.io Review (2026): Pricing & Alternatives | Stork.AI,
+>    [https://www.stork.ai/en/idlen-io](https://www.stork.ai/en/idlen-io)
+> 13. Launch HN: Codebuff (YC F24) – CLI tool that writes code for you | Hacker News,
+>    [https://news.ycombinator.com/item?id=42078536](https://news.ycombinator.com/item?id=42078536)
+> 14. Please add support for old cpu's · Issue \#497 · CodebuffAI/codebuff \- GitHub,
+>    [https://github.com/CodebuffAI/codebuff/issues/497](https://github.com/CodebuffAI/codebuff/issues/497)
+> 15. GitHub \- Quorinex/Freebuff2API: OpenAI-compatible Freebuff proxy with dynamic free-agent tracking, token
+>    rotation, and ready-to-use Docker deployment.,
+>    [https://github.com/Quorinex/Freebuff2API](https://github.com/Quorinex/Freebuff2API)
+> 16. CodeBuff: The Open-Source Multi-Agent AI Coding Revolution | atal upadhyay,
+>    [https://atalupadhyay.wordpress.com/2026/03/04/codebuff-the-open-source-multi-agent-ai-coding-revolution/](https://atalupadhyay.wordpress.com/2026/03/04/codebuff-the-open-source-multi-agent-ai-coding-revolution/)
+> 17. Remove shimmer animation from freebuff waiting room Wait time (\#523) · CodebuffAI/codebuff@9099292 \-
+>    GitHub,
+>    [https://github.com/CodebuffAI/codebuff/actions/runs/24651667103](https://github.com/CodebuffAI/codebuff/actions/runs/24651667103)
+> 18. codebuff/sdk/src/client.ts at main \- GitHub,
+>    [https://github.com/CodebuffAI/codebuff/blob/main/sdk/src/client.ts](https://github.com/CodebuffAI/codebuff/blob/main/sdk/src/client.ts)
+> 19. Free CLI agent — unlimited DeepSe… for students | StudentOffers.co,
+>    [https://www.studentoffers.co/offer/freebuff](https://www.studentoffers.co/offer/freebuff)
+> 20. Rate-limit freebuff GLM sessions to 5 per 20 hours · CodebuffAI/codebuff@7dd903b \- GitHub,
+>    [https://github.com/CodebuffAI/codebuff/actions/runs/24808282674](https://github.com/CodebuffAI/codebuff/actions/runs/24808282674)
+> 21. Rate-limit freebuff GLM sessions to 5 per 20 hours (\#537) · CodebuffAI/codebuff@585260b,
+>    [https://github.com/CodebuffAI/codebuff/actions/runs/24915163705](https://github.com/CodebuffAI/codebuff/actions/runs/24915163705)
+> 22. freebuff2api-openai-proxy | Skills M... \- LobeHub,
+>    [https://lobehub.com/bg/skills/aradotso-trending-skills-freebuff2api-openai-proxy](https://lobehub.com/bg/skills/aradotso-trending-skills-freebuff2api-openai-proxy)
+> 23. Freebuff: The 100% free coding agent \- Y Combinator,
+>    [https://www.ycombinator.com/companies/freebuff](https://www.ycombinator.com/companies/freebuff)
+> 24. codebuff/README.md at main \- GitHub,
+>    [https://github.com/CodebuffAI/codebuff/blob/main/README.md](https://github.com/CodebuffAI/codebuff/blob/main/README.md)
+> 25. codebuff/README.zh-CN.md at main \- GitHub,
+>    [https://github.com/CodebuffAI/codebuff/blob/main/README.zh-CN.md](https://github.com/CodebuffAI/codebuff/blob/main/README.zh-CN.md)
+> 26. Codebuff download | SourceForge.net,
+>    [https://sourceforge.net/projects/codebuff.mirror/](https://sourceforge.net/projects/codebuff.mirror/)
+> 27. Antigravity IDE, [https://antigravityide.net/](https://antigravityide.net/)  
+> 28. Google Antigravity CLI features,
+>    [https://antigravity.google/docs/cli-features](https://antigravity.google/docs/cli-features)
+> 29. Codebuff \- Copilot Alternatives,
+>    [https://copilot-alternatives.com/alternative/codebuff/](https://copilot-alternatives.com/alternative/codebuff/)

package/docs/agents-and-tools.md

@@ -0,0 +1,217 @@
+# Agents and Tools
+
+> **Last verified:** 2026-07-23 — source reads of all agent definitions + `common/src/tools/constants.ts`.
+
+## Agents
+
+The Savant harness ships 9 canonical agents + 5 helper tool-library agents from the `agents/` workspace. Each agent is a
+`SecretAgentDefinition` with a restricted tool set — no agent may perform another agent's role (ECHO Law: Separation of
+Duties).
+
+### Canonical 9-Agent Roster
+
+| # | Agent | ID | Phase | Responsibility | Tools |
+|---|-------|----|-------|----------------|-------|
+| 1 | **Orchestrator** | `savant` | ALL | Routes work, enforces ECHO Protocol, spawns all agents | `spawn_agents`, `read_files`, `read_subtree`, `run_readonly_command`, `write_todos`, `suggest_followups`, `ask_user`, `read_url`, `skill`, `set_output`, `list_directory`, `glob`, `render_ui`, `gravity_index`, `transition_phase`, `write_file`, `str_replace`, `apply_patch` |
+| 2 | **Detective** | `detective` | RED | Codebase analysis, grep call-graphs, catalog evidence | `code_search`, `set_output`, `list_directory`, `glob`, `read_files`, `read_subtree` |
+| 3 | **Forge** | `forge` | GREEN | Implementation only — writes code from converged FID | `write_file`, `str_replace`, `set_output` |
+| 4 | **Verifier** | `verifier` | AUDIT | Double-audit, run tests, check call-graph reachability | *(reads via message history — no write tools)* |
+| 5 | **Recorder** | `recorder` | FID | Create, track, archive FIDs. Update CHANGELOG | `write_file`, `read_files`, `glob`, `code_search`, `set_output` |
+| 6 | **Thinker** | `thinker` | Planning | Deep reasoning via sequential thinking engine | `sequentialthinking` |
+| 7 | **Scout** | `scout` | Explore | File/code search, glob, read subtrees, context gathering | `glob`, `list_directory`, `read_files`, `read_subtree`, `set_output` |
+| 8 | **Researcher** | `researcher-web` / `researcher-docs` | Research | Web search, documentation lookup | `web_search`, `read_url` (web) · `read_docs` (docs) |
+| 9 | **Scribe** | `scribe` | Docs | Session summaries, LESSONS.md, knowledge files | `read_files`, `write_file`, `glob`, `code_search`, `set_output` |
+
+### Helper Tool-Library Agents & Specialist Variants
+
+These are consumed by the canonical 9 roles but do NOT constitute independent
+conversational agents. (The final row is a canonical thinker variant listed
+here because it is not spawnable by the Orchestrator's `spawnableAgents`; it is
+spawned by Free/SavantFree prompts.)
+
+| Agent | ID | Tools | Consumed By |
+|-------|----|-------|-------------|
+| **Basher** | `basher` | `run_terminal_command` | Orchestrator (terminal commands) |
+| **tmux-cli** | `tmux-cli` | `run_terminal_command`, `read_files`, `set_output`, `add_message` | Orchestrator (interactive CLI testing) |
+| **browser-use** | `browser-use` | `set_output`, `run_terminal_command`, `add_message` | Orchestrator (browser automation) |
+| **Context Pruner** | `context-pruner` | *(no explicit toolNames — uses `set_messages` via runtime)* | Orchestrator (auto-spawned for long sessions) |
+| **Thinker (Gemini w/ files)** | `thinker-with-files-gemini` | *(no model-visible tools; `read_files` via `programmaticToolNames`)* | Free/SavantFree (reasoning with file context, FID-2026-0803-001 ECHO-2) |
+
+### Directory Layout
+
+```text
+agents/
+├── savant/              # Orchestrator (savant.ts + mode variants)
+├── detective/           # RED phase
+├── forge/               # GREEN phase
+├── verifier/            # AUDIT phase
+├── recorder/            # FID lifecycle
+├── thinker/             # Sequential thinking
+├── scout/               # File/code search
+├── researcher/          # Web + docs research (researcher-web.ts, researcher-docs.ts)
+├── scribe/              # Session documentation
+├── browser-use/         # Browser automation helper
+├── editor/              # Editor scaffolding (used by `init` command)
+├── file-explorer/       # File listing helper
+├── librarian/           # Knowledge/context helper (used by context-pruner)
+├── types/               # Shared TypeScript types across agents
+├── base-chat.ts         # Base chat agent shared logic
+├── basher.ts            # Terminal command agent
+├── context-pruner.ts    # Context pruning agent
+├── constants.ts         # Publisher constant
+├── tmux-cli.ts          # Interactive CLI testing agent
+└── package.json         # @savant-code/agents workspace
+```
+
+### Separation of Duties
+
+| Rule | Enforcement |
+|------|-------------|
+| Orchestrator cannot write source code | `write_file`/`str_replace` gated to GREEN phase + FID path exemptions only |
+| Forge cannot verify its own work | No `run_terminal_command`, no test access |
+| Verifier cannot write code | No `write_file`/`str_replace` — reads via message history |
+| Detective cannot implement fixes | No `write_file`/`str_replace` |
+| Recorder controls FID lifecycle exclusively | Only Recorder archives FIDs |
+| Thinker must use sequential thinking | `sequentialthinking` is its only tool |
+
+---
+
+## Tools
+
+Tool definitions live in `common/src/tools/` and are executed via the SDK helpers + agent-runtime. Each tool has a Zod
+input schema, output schema, and an `endsAgentStep` flag.
+
+### Tool Catalog
+
+#### File Operations
+
+| Tool | Description | FSM Gate |
+|------|-------------|----------|
+| `write_file` | Create or overwrite a file | GREEN only |
+| `str_replace` | Exact string replacement in a file | GREEN only |
+| `apply_patch` | Apply a unified diff patch | GREEN only |
+| `read_files` | Read one or more files | None |
+| `read_subtree` | Read a directory tree recursively | None |
+
+> **Checkpointing:** the write-gate in `executeToolCall` (agent-runtime) captures the pre-edit content of every
+> file before `write_file`/`str_replace`/`apply_patch` dispatch, per user turn (FID-2026-0803-004). Subagent
+> writes inherit the parent turn via spawn context; terminal side effects are never captured. The CLI surfaces
+> this as `/rewind` (code / conversation / both / fork).
+
+#### Search & Navigation
+
+| Tool | Description | FSM Gate |
+|------|-------------|----------|
+| `glob` | Pattern-match files by name | None |
+| `list_directory` | List directory contents | None |
+| `code_search` | Search file contents with regex | None |
+| `find_files` | Find files by name pattern | None |
+| `read_url` | Fetch content from a URL | None |
+| `read_docs` | Read documentation files | None |
+
+#### Agent Orchestration
+
+| Tool | Description | FSM Gate |
+|------|-------------|----------|
+| `spawn_agents` | Spawn one or more sub-agents | None (template-level restriction) |
+| `spawn_agent_inline` | Spawn agent inline (internal) | None |
+| `set_output` | Set output for parent agent | None |
+| `ask_user` | Ask the user a question | None |
+| `suggest_followups` | Suggest follow-up actions | None |
+| `add_message` | Add a message to the conversation | None |
+
+#### Execution
+
+| Tool | Description | FSM Gate |
+|------|-------------|----------|
+| `run_terminal_command` | Run a shell command | AUDIT only |
+| `run_readonly_command` | Run a read-only shell command | None |
+| `run_file_change_hooks` | Run file change hooks | None |
+
+#### Planning & State
+
+| Tool | Description | FSM Gate |
+|------|-------------|----------|
+| `transition_phase` | Transition the Perfection Loop FSM | None (validates legal transitions) |
+| `create_plan` | Create a development plan | None |
+| `write_todos` | Write a TODO list | None |
+| `add_subgoal` | Add a subgoal to the current plan | None |
+| `update_subgoal` | Update an existing subgoal | None |
+| `task_completed` | Mark a task as completed | None |
+
+#### Reasoning & UI
+
+| Tool | Description | FSM Gate |
+|------|-------------|----------|
+| `sequentialthinking` | Structured stepwise reasoning | Thinker only |
+| `think_deeply` | Deep thinking prompt | None |
+| `render_ui` | Render visual widgets (table, card, stepper, badge, etc.) | None |
+| `skill` | Load a skill from the skills directory | None |
+| `gravity_index` | Index codebase for gravity-aware search | None |
+| `web_search` | Search the web | None |
+
+#### Infrastructure
+
+| Tool | Description | FSM Gate |
+|------|-------------|----------|
+| `end_turn` | End the current turn | None |
+| `set_messages` | Set conversation messages (internal) | None |
+| `set_scaffold_complete` | Mark scaffold mode as complete | None |
+| `lookup_agent_info` | Look up agent metadata | None |
+| `propose_str_replace` | Propose a string replacement (Forge) | None |
+| `propose_write_file` | Propose a file write (Forge) | None |
+| `browser_logs` | Get browser automation logs | None |
+
+#### Composio (disabled)
+
+| Tool | Description |
+|------|-------------|
+| `composio_manage_connections` | Manage Composio connections |
+| `composio_multi_execute_tool` | Execute multiple Composio tools |
+| `composio_search_tools` | Search Composio tools |
+| `composio_get_tool_schemas` | Get Composio tool schemas |
+
+> **Note:** Composio tools are disabled (`ENABLE_COMPOSIO_TOOLS = false` in `agents/savant/savant.ts:16`).
+
+### Tool Count
+
+- **Total registered tools:** 40 (including Composio meta-tools)
+- **Published tools (available to agents):** 30
+- **FSM-gated tools:** 3 (`write_file`, `str_replace` → GREEN; `run_terminal_command` → AUDIT)
+- **Agent-exclusive tools:** 1 (`sequentialthinking` → Thinker only)
+
+### FSM Phase Gating
+
+Tools are gated by FSM phase in `packages/agent-runtime/src/tools/tool-executor.ts`:
+
+```text
+write_file / str_replace / apply_patch  →  GREEN only
+run_terminal_command                    →  AUDIT only
+sequentialthinking                      →  Thinker only (agent ID starts with "thinker")
+```
+
+Gate logic: `(agentState.fsmPhase ?? 'idle') !== 'green'` — subagents inherit `fsmPhase` from parent via
+`createAgentState()` in `spawn-agent-utils.ts`.
+
+### Tool Integration Points
+
+| Layer | File | Role |
+|-------|------|------|
+| Tool definitions | `common/src/tools/constants.ts` | `toolNames[]` array, `publishedTools[]` array |
+| Tool schemas | `common/src/tools/params/tool/*.ts` | Zod input/output schemas per tool |
+| Tool compilation | `common/src/tools/compile-tool-definitions.ts` | Compiles tool defs for runtime |
+| Tool execution | `packages/agent-runtime/src/tools/tool-executor.ts` | FSM gating, phase validation |
+| Tool handlers | `packages/agent-runtime/src/tools/handlers/tool/*.ts` | Per-tool execution logic |
+| MCP tools | `packages/agent-runtime/src/mcp.ts` | MCP server tool loader |
+| Skills | `packages/agent-runtime/src/tools/handlers/tool/skill.ts` | Skill loader (4 directories) |
+| SDK bridge | `sdk/src/run.ts` | Streams tool calls to CLI |
+
+### Shell Shims
+
+Direct commands without `savant-code` prefix:
+
+```bash
+savant-code shims install savant-code/savant@1.0.0
+eval "$(savant-code shims env)"
+savant "fix this bug"
+```