πPrivacy by design
Don't want an AI using your personal data?
TokenSoup redacts names, IDs, IBANs, cards and emails before anything is sent to a model.
The safest data is the data that never left your computer.
Runs on your own computer. Does the cheap, deterministic work with scripts β for free β and saves the model for what actually needs thinking.
TokenSoup redacts names, IDs, IBANs, cards and emails before anything is sent to a model.
The safest data is the data that never left your computer.
git status?Deterministic work runs as a local script β and reuses the scripts you already trust. No round trip, no cost.
The cheapest token is the one you never spend.
Reject a command and it stays rejected β the model can't bypass you by switching tools or rewording the path.
You stay in control of your own machine.
A coordinator splits the work across parallel agents β frontier to plan, cheap or local models for the legwork.
Orchestrate many models, not just pick one.
Any MCP client β Claude Code, Cursor, Cline β can call TokenSoup's tools; TokenSoup can use other MCP servers too.
A good neighbor in your toolchain.
Deterministic work and scripts you already trust shouldn't cost a single token.
Most cloud agents answer βgit statusβ or βis this valid JSONβ by shipping your context to a model and paying for the round trip. TokenSoup recognizes those, runs a local routine instead, and only reaches for a model β the right-sized one β when the task genuinely needs reasoning. It runs on your machine, redacts personal data before anything leaves it, and asks before doing anything destructive.
A finished, self-hosted assistant you launch with a double-click and talk to in your browser, terminal, or a chat app. One API key to start. Built for a computer-comfortable person, not just developers.
Not a developer library you import into your code, and not trying to compete with those. Those are toolkits for engineers building agent systems. TokenSoup is the finished assistant itself.
Spend nothing where nothing needs spending; spend modestly where a small model suffices; spend fully only on the hard parts.
Deterministic tasks β git status, file counts, JSON checks, format checks β run as built-in indie scripts, not model calls. The smart router recognizes them and runs the local routine automatically. The assistant can also author a new reusable script when it meets a repeatable task β shown to you for approval before anything is saved.
Already have battle-tested glue in Bash, PowerShell, Python, or Node β or a compiled binary? Register it as an indie agent and TokenSoup calls it directly instead of re-implementing, and re-paying for, the same logic in an LLM. Your legacy automation becomes part of the assistant.
When a model is needed, the router classifies the task and routes it: simple text to a cheap/fast model, standard work to a mid model, heavy work to a frontier model. A semantic cache returns repeated answers with no new call.
An AST knowledge graph of your code, built locally with no model calls. Ask about your codebase and TokenSoup feeds the model the exact symbols and file locations instead of dumping whole files β far fewer tokens. Build it with one click in the web UI (or /project map); once built, relevant context is added automatically. It can auto-refresh itself after edits (opt-in, incremental, in the background).
Short instruction sets β testing, git, security, and your own β are injected into the prompt only when a message is actually relevant to them, never all at once. Add, remove, and toggle each one from the web UI; a disabled skill is never detected or injected, so it costs nothing.
For large code files, TokenSoup sends a structural skeleton β imports and function/class signatures with line numbers β instead of the whole file, and the assistant asks for exact line ranges when it needs the body. A Full / Balanced / Lean switch tunes how aggressive this is, and the UI shows how many tokens it saved.
| Scenario | Typical baseline | With TokenSoup |
|---|---|---|
| Git operations | ~500 tok / query | 0 tok Β· indie |
| Repeated queries | ~1000 tok | 0 tok Β· cache |
| Simple tasks | ~800 tok Β· large model | ~200 tok Β· small model |
| Email triage | ~2000 tok / email | ~200 tok Β· small model |
| Large code file read | ~36k tok Β· whole file | skeleton + ranges |
benchmark/: the deterministic mechanisms β skeletons, skill gating, SoupGraph context β are measured directly (run python3 benchmark/suites/run_all.py), and an end-to-end token/cost A/B against a direct frontier-model call is runnable with an API key (benchmark/suites/bench_e2e.py) β it shows ~59% lower dollar cost with accuracy preserved. Each test also checks correctness, since saved tokens only count if the answer is still right.Safety is layered, on the assumption that a tool which can run commands needs guardrails β not blind trust. This security work is complete and shipped in v1.0, validated by an end-to-end benchmark. See SECURITY.md for the honest trust model & limits.
Emails, IDs, IBANs, phone numbers replaced with placeholders before anything is sent to a model.
User messages checked for prompt-injection patterns.
Web and file content passes the same guard before it can influence the model.
Secret markers in context detect exfiltration attempts.
The final response is scanned before it's shown to you.
API keys encrypted at rest (AES-256-GCM); localhost-only by default.
Dangerous operations require your explicit approval. Reject a file operation and that path is protected against every tool β bash, write_file, edit_file, python -c, shell redirects β for the rest of the turn. The model can't bypass your rejection by switching tools or rewording the path, and an already-rejected command won't re-prompt until you ask for it again yourself. Destructive writes that would clobber an existing file require confirmation.
TokenSoup assumes a single trusted operator per instance. Everything the agent reads from the outside β web pages, files, messages β is treated as untrusted. It is not a hostile-multi-tenant boundary: to run code for mutually distrusting users, isolate at the infrastructure level (separate instances, credentials, and ideally hosts or VMs).
The layers above reduce risk and limit blast radius β they do not make it zero. OS-level isolation (bubblewrap / WSL2 / containers, Enterprise) shares the host kernel and is not a hypervisor; the soft folder sandbox is a parser and can be defeated by obfuscation; prompt injection can attempt to hijack the agent. Channels deny by default until you set their allowlist or pair a user in (or deliberately open them), and an optional audited break-glass can run a command unsandboxed β but only for the owner (solo) or an RBAC tools.elevated role (Enterprise), never a paired guest. For adversarial, multi-tenant, or regulated workloads, run TokenSoup inside a dedicated VM and treat these as an inner layer, not the boundary.
Provided under Apache-2.0, βAS ISβ, without warranty; this is not legal advice. Full details: SECURITY.md.
Unlike a gateway that fans messages out to channels, TokenSoup sends every request down through layers β one engine applies redaction, caching, and routing, then branches to a free local script or a right-sized model, with your approval guarding anything destructive.
TokenSoup speaks the Model Context Protocol in both directions: any MCP client (Claude Code, Cursor, Cline, β¦) can call TokenSoup's tools, and TokenSoup can call out to other MCP servers.
A separate, experimental layer: hand it a slow Python function and it benchmarks, proposes a port to Rust/C/Go/COBOL, waits for your approval, compiles, and verifies the result matches. Registering the artifact as an indie agent is a deliberate second step.
A coordinator breaks a complex task into subtasks and runs workers in parallel β and each agent can run a different model, including a local one. Use a frontier model to plan, cheap or local models for the legwork, a strong model to synthesize.
And there's more under the hood β durable multi-step flows that survive a session restart, an autonomous agent mode, scheduled cron tasks, batch processing, a semantic cache, and per-agent security profiles. TokenSoup is built to bend to how you work, not the other way around.
First run installs dependencies, asks for one API key, and opens the web UI at http://localhost:7070.
# From the extracted folder > cd path\to\tokensoup > python soup.py
$ cd tokensoup $ bash install.sh # or: python3 soup.py
$ cd tokensoup $ bash install.sh # or: python3 soup.py
| Flag | What it does |
|---|---|
| python soup.py | Web UI at localhost:7070 (default) |
| --cli | Terminal chat instead of the web UI |
| --reset | Re-enter API keys |
| --check | Check installation state |
| --lang en | sr | Force English or Serbian |
| --port 8080 | Custom port |
All commands are typed directly in chat. Arguments in [brackets] are optional. Full reference also lives in COMMANDS.md.
No commands match that filter.
/new [name]New session
/sessionsList all sessions
/statusSession status β tokens, model, cost
/contextContext window details
/clearClear conversation history
/compactCompress context
/memoryShow MEMORY.md
/resume [name]Resume previous session
/model <name>Switch model
/modelsList available models
/lang <code>Interface language
/config get <key>Read setting
/config set <key> <val>Set value
/config listAll settings
/security statusSecurity layer overview
/security pii on|offPII redaction
/security set <name>Security profile (full/standard/minimal/monitor/off)
/vault set <key> <val>Store encrypted value
/vault get <key>Get encrypted value
/config key <provider> <key>Set/update an API key
/doctorDiagnostic β checks keys & providers
web UI Β· SettingsManage keys in the interface
/agent <task>Run autonomous agent
/agent stopStop agent
/agent statusAgent status
/agent sandbox on|offSandbox isolation
/agent capabilitiesAllowed tools
/hitl on|offRequire approval before each step
/hitl strictApproval for ALL bash commands
/hitl trust <category> [session|always|never]Trust policy for a risky-op category
/hitl memory [clear]Show/clear remembered trust decisions
/approveApprove pending step
/observe on|offMonitor agent activity
/router statusSmart router status
/router set <tier> <model>Model for a tier
/si <task>Self-improve agent
Local scripts that run without API calls.
/indie listAll registered agents
/indie run <name> [args]Run an agent
/indie new <name>Create template
/indie register <name> <path>Register a script
/indie create "<desc>"LLM generates + registers
/indie remove <name>Remove agent
/indie info <name>Agent details
git_statusgit_diffgit_loggit_commitfile_statsfile_findjson_validatejson_formatsystem_infodisk_usageweb_scrapesession_summarysoupgraph_query/cache on|offToggle semantic cache
/cache statusHit rate and stats
/cache semanticSemantic matching mode
/cache exactExact-match mode only
/cache modelShow/set embedding model
/cache installInstall sentence-transformers (once)
/cache threshold <0-1>Similarity threshold (default 0.85)
/cache ttl <sec>Entry time-to-live
/cache refreshRe-embed cached entries
/cache flushClear cache
Batch API costs 50% less; results within 24h.
/batch create <name>New batch job
/batch add <name> <prompt>Add item
/batch run <name>Submit
/batch status <id>Check status
/batch results <id>Get results
/team create <name>Create team
/team add <team> <agent>Add agent
/team run <name> <task>Run team task
/team status <name>Team status
/team listAll teams
/economy on|offEconomy mode β minimize cost
/budget set <type> <amt>Spend limits (session/daily/tokens)
/ratelimit set <provider> β¦Per-provider rate limits
/flow start <name>Start flow
/flow listActive flows
/flow resume <id>Resume paused flow
/flow stop <id>Stop flow
/goal <desc>Autonomous run toward a goal
/cron listSchedule recurring jobs
/notifyNotification channels
/changelogShow recent changelog
/email triageTriage inbox
/email draft <to> <subject>Draft email
/email send <id>Send drafted email
/email configEmail settings
/generate <image|video|audio> <model> <prompt>Generate media
/marketing <topic>Marketing content pipeline
/mediaList media generations
/project mapBuild AST knowledge graph (0 tokens)
/project map <query>Search codebase
/project loadLoad project context (uses graph)
/indie soupgraph_query <query>Search via indie agent
/skillsList available skills
/skill <name>Show a skill
web UI Β· Agents β SkillsAdd, remove, enable/disable
/commitStage & commit with an AI message
/diffShow working-tree diff
/reviewAI review of current changes
/prDraft a pull request from commits
/verify on|offVerify model output (read or execute)
/improve <task>Propose & apply code improvements
/effort low|medium|maxReasoning effort (cost knob)
/ultraplan <task>Deep multi-step planning session
/auditSecurity audit + history
/tasksProject task/TODO manager
/polyglot scanPerf layer β compiler scan & optimize
/project initInitialize project
/mcp connect <url>Connect MCP server
/mcp listConnected servers
/mcp toolsAvailable MCP tools
/mcp disconnect <id>Disconnect server
/search <query>Web search
/fetch <url>Fetch URL content
/saveSave session (memory + snapshot)
/dreamConsolidate session memory now
/voiceVoice mode
/vimVim input mode
/doctorFull diagnostic check
/help [command]List commands / command help
/costToken cost summary
/exportExport session to Markdown
/versionTokenSoup version
You want a capable assistant you launch with a double-click and talk to in a browser β not a CLI tool that assumes you live in a terminal.
You want the assistant on your own machine, with personal data redacted before anything leaves it, and a clear say over destructive actions.
One self-hosted helper for everyday work. An Enterprise module (in development) will add team features, stronger controls, auditable oversight, and the option of a fully local model behind your firewall β all on the same core engine.
benchmark/suites/bench_e2e.py.