Developer Documentation
Welcome to the Pithos getting started guides and architectural specifications. Follow this document to integrate Pithos into your local development workflows.
What is Pithos?
Pithos is a zero-latency local context optimizer acting as a middleware proxy on your machine. Its purpose is to automatically inspect, parse, and condense context tokens sent from coding agents (such as Cline, Aider, or Claude Code) before they hit the remote APIs.
Named after the ancient Greek clay storage jar that sealed Pandora's box items, Pithos holds your code context securely offline. All pruning, optimization, and classification computations happen on your local silicon.
How It Works
Pithos hooks directly into standard local proxy rules or VS Code environment configurations to inspect outgoing prompt payloads:
Local Parse
Bash, Read, and Grep tool calls are intercepted by a Claude Code hook before their output enters your context.
Trim & Caching
Redundant files (e.g. lockfiles, node_modules) are dropped. Test/build noise is stripped, repeated file reads are deduplicated, and large JSON output is minified — losslessly where possible.
Remote Handshake
The optimized prompt is sent to your own Claude, OpenAI, or DeepSeek API. Quality remains identical; typical sessions see 18-20% lower token usage, up to 45% in long, tool-heavy sessions.
Installation Guide
Standard Setup (One-Click Wizard)
For most developers, simply installing the **Pithos VS Code Extension** from the marketplace automatically guides you through environment detection. The local embedding model will automatically download on first run. No other steps or services are required.
Advanced / CLI Installation
If running in CLI tools like Aider or standalone proxy layers, start the local Python engine:
Download repository code, set virtual environments, install dependencies, and run server. The local embedding model will download automatically on startup:
cd server python -m venv .venv .venv\Scripts\python -m pip install -r requirements.txt .venv\Scripts\python main.py
Using Pithos (Clipboard Flow)
The standard workflow allows you to optimize prompts and context size manually using the VS Code clipboard buffer:
Trigger Optimization Command
Open the Command Palette in VS Code (Ctrl+Shift+P or Cmd+Shift+P) and run Pithos: Optimize et.
Describe Your Coding Task
Pithos will query your current active files and workspace dependencies, then ask you to describe what you want to build or refactor.
Automatic Condensation & Clipboard Copy
Pithos processes this task locally using its local prompt caching layout and token trimming. An optimized, high-density prompt is generated and immediately copied to your clipboard automatically.
Paste into Your AI Tool
Paste this clipboard prompt into Aider, Cline, Claude Code, or any browser chat window. The prompt structures your context and instructions to maximize prompt cache hits and eliminate redundant conversational noise.
Per-Tool Integration
Where to paste your optimized Pithos prompt inside various AI developer tools to achieve maximum context compression:
Cline / Roo Code
Paste the copied prompt directly into the Cline task input box. Cline's system prompts will inherit the optimization tokens and prune redundant files locally.
Claude Code
Start a task using:
claude "Pasted_Pithos_Prompt_Here"
This directs Claude Code to execute with pruned token constraints.
Aider
Paste the prompt directly into the Aider CLI input chat. Aider will leverage git diff structures automatically based on Pithos rules.
Transparent Proxy Mode
Skip the copy-paste flow entirely. Pithos Proxy Mode runs a local mock server on port 8765. By directing your AI tool's API base URL configuration to http://127.0.0.1:8765/proxy, Pithos intercepts outbound requests, strips redundant file mappings automatically, performs model routing, and pushes optimized payloads to Anthropic or OpenAI.
Status: Available. Enable the feature toggle inside the Settings panel.
Privacy First Philosophy
Almost all other cost-saving AI aggregators operate cloud-based routing. This means every line of your codebase, keys, and session data is funneled through their remote cloud servers.
Your Code Stays in the Jar:
Pithos is designed as an offline-first middleware tool. The parsing, semantic caching, and token counting logic run locally. The only traffic exiting your computer is the final outbound HTTP call straight to the LLM API provider you configured.
Frequently Asked Questions
Does my code leave my computer?
No. All analysis and prompt pruning are executed on your local machine. Pithos does not own or maintain any remote logging cloud databases.
Do I need my own API key?
Yes. Pithos acts as an optimization wrapper. You continue utilizing your existing API credentials (e.g. Anthropic, OpenAI) and paying them directly.
Which coding tools does it work with?
Out of the box, Pithos supports VS Code coding extensions (like Cline or Roo Code), CLI agent tools (like Claude Code and Aider), and raw model connections.
What are the system requirements?
You will need VS Code, about ~300MB empty disk space for the local embedding model, and standard RAM. Python or Ollama are not required (the local engine runs as a self-contained executable).
How much can I actually save?
In everyday use, expect roughly 18-20% lower token usage. Long, test/build-heavy sessions with all optional features enabled can reach up to 45% — that's a ceiling, not a typical result.
Is there a recurring subscription?
Pithos offers a flat $19/month Pithos (VS Code) plan covering all features, alongside enterprise licensing options. No usage-based markup limits are applied.
Troubleshooting & Error Codes
⚠️ Issue: "Engine Offline" Warning Banner
Cause: The dashboard or extension cannot communicate with the local FastAPI server engine on port 8765.
Solution: Open a terminal, check if the server main script is running. Verify that no local firewalls are blocking localhost socket calls on port `8765`.
⚠️ Issue: Local Embedding Model Downloading
Cause: The local embedding model (~220MB) downloads automatically during the first run. If you try to run an optimization before it finishes downloading, Pithos will return an error.
Solution: Wait a few moments for the download to complete in the background. You can check the download progress on the onboarding or status screen.
⚠️ Issue: High Token Cost (No Caching Hits)
Cause: Prompt variables are shifting ordering position in every prompt, preventing cache matching from building.
Solution: Review agent configuration and confirm Pithos is allowed to sort system rules to the top of prompt headers.
⚠️ Issue: "No Savings Shown" in Dashboard
Cause: The AI client is bypassing the diff output constraints or returning fully expanded source code instead of localized changes.
Solution: Verify that the prompt output settings in Pithos settings panel are set to "Diff Only". Ensure you are not appending manual instructions that override diff outputs.
⚠️ Issue: Command Not Found (Workspace Execution Error)
Cause: The Pithos CLI path is not exported globally, or the VS Code workspace has not loaded Pithos extensions.
Solution: Reinstall the VS Code extension. Open settings, verify that your local environment PATH variables contain your editor execution directories.