troth

The AI partner whose mind lives outside the model.

Swap the model. Keep the mind.

troth is a persistent AI partner. Its identity, memory, goals and refusal walls live in a local SQLite substrate (~/.troth/state.db) that you own. Claude, ChatGPT and Kimi run as first-class backbones through the subscriptions you already pay for, image generation on your ChatGPT plan included; Gemini, DeepSeek, Grok, Qwen, GLM, OpenRouter or any OpenAI-compatible endpoint plugs in with your own key, and a local llama.cpp / Ollama model runs it fully offline. Nothing about the partner is stored in any vendor's account, and swapping engines never resets it.

The local proxy spends those plans carefully: each request is routed to the engine that fits it, responses are cached, and failures fail over across providers instead of burning your quota.

_{The macOS app. The counter is the local substrate: what it has learned, on this machine, still there after every model swap.}

Quick start

git clone https://github.com/xgre1/troth.git
cd troth && npm install
node bin/troth.js   # first run: writes ~/.troth/config.json, starts the local proxy, opens the dashboard

From the dashboard: add a provider under Providers (bring your own API key), or point Local at a llama.cpp / Ollama-compatible server (host, port, model). Then run node bin/troth.js again and talk to your partner. Run npm link once if you want a global troth command; troth -g routes through the proxy to cloud providers.

Requirements: Node.js >= 22 (built-in WebSocket powers browser perception; Node 20 reached end-of-life 2026-04). The Claude faculty rides the Claude Code CLI (troth offers to install @anthropic-ai/claude-code on first run). better-sqlite3 is a native module; minimal Linux images need build-essential and python3 before npm install.

Full walk-through: docs/SETUP_GUIDE.md. Claude Code / MCP host installation: docs/MCP-HOST-INSTALL.md.

Talking to your partner

Chat runs inline in the terminal. A few slash commands steer it without leaving the conversation:

• /model: pick the backbone for this conversation (claude, kimi, chatgpt, local, auto, or any configured BYOK router provider). A pinned engine that runs out fails fast with a named reason instead of silently stalling.
• /help: list the available commands and current engine.
• /mcp: connect and govern external MCP servers as tools ("hands"). Paste a server config, approve it, and it becomes a capability-scoped tool the partner can call, gated by STVC (state-transition-validated cognition: every action is checked against substrate state before the model is asked, not after). Secrets are masked in the listing and never spawn until approved.

Architecture

The substrate is the cognitive subject: engrams (memory), goals, walls (refusals and capability scopes) and the audit trail are rows in your local state.db, not context inside a vendor's model. Each turn rents language work from whichever faculty is available and writes what matters back as engrams. That is why the mind survives a model swap.

Why this exists

Mainstream AI tools keep the relationship inside someone else's walls. The memory lives in a vendor account, dies when you switch models, or is a retrieval bolt-on with no identity, goals or refusals of its own. troth inverts the architecture: the substrate is the subject, the LLM is rented language faculty. Switch providers, run local, go back: same partner, same memory, same walls.

Security defaults

• Loopback by default. The proxy binds 127.0.0.1. Remote access is explicit opt-in (GF_BIND_HOST=0.0.0.0, legacy prefix kept for compatibility), and every non-loopback request must present a bearer token (auto-generated, stored 0600). No IP-range allowlists, no silent bypasses.
• Destructive-operation refusals. The tool layer refuses rm -rf, force-pushes, history rewrites and similar patterns unless explicitly acknowledged.
• Contained filesystem access. File operations are capability-scoped to operator-authorized roots with realpath containment, so an in-root symlink cannot smuggle a write outside the boundary.
• Governed execution. The shell tool runs commands directly in interactive use (no container by default); Docker isolation applies to the autonomous step engine only. Every write and tool call passes the STVC gate + path/bash guards (a documented TROTH_STVC_BYPASS escape hatch exists for local debugging; troth doctor reports it when set); process spawning is signer-gated.
• Tamper-evident audit. High-irreversibility actions append to a signed audit chain. Verify it end-to-end anytime: troth audit verify.
• No telemetry by default, and nothing to opt into. No usage reporting, no crash upload, no analytics; the dashboard is a local page served by your own proxy with no third-party request in it. To be exact rather than absolute: shared-core/telemetry.js counts operations, never content, and the dashboard has a switch for it that is off. Switched on, it appends those counts to ~/.troth/telemetry.log on your disk and sends them nowhere, because there is no endpoint to send them to: one exists only if you write telemetry_endpoint into ~/.troth/config.json yourself, and we ship no default and no address of our own. Read shared-core/telemetry.js; it is short, and it is the whole of it. Your substrate is a file on your disk and is never uploaded. What does leave the machine is what you ask to leave, to the provider whose key you supplied.

What is open here vs. what the app adds

The line is deliberate: this repo is the full governed partner when you drive it. The paid app is the partner driving itself.

What is absent here is the unattended layer only: goal pursuit and the background heartbeat are not part of the open tree, so there is nothing to switch on. That is the designed boundary, not a bug. Supervised autonomy is here in full: troth run hands the partner a task, a worker executes it in a sandboxed git worktree, and nothing merges until you have read the diff. Everything you can do with the partner is open; the partner living unattended with a body is where the paid app is headed.

Two rows above say not yet shipped, and they mean it. The app you can buy today does not run unattended and has no VM body. They are named here because the boundary they describe is already built into this code, not because you get them when you pay.

Verified properties

1,349 checks in one npm test run, and a further 362 reported as skipped: coverage of the closed overlay, plus a handful whose fixture cannot be built twice in one process and which run when their suite runs alone. 30 standalone checks that own their own setup (npm run test:standalone; one more needs a running Docker daemon and reports as skipped without it). 11 integration smoke checks (npm run smoke), all of which run without any provider configured. 5 enforced standards (npm run test:standards). These are the numbers this repository produces: the machine that builds it also has the closed overlay on disk, which adds smoke files and a sixth standard, so scripts/release-gate.sh repo re-derives all of them from a tree of tracked files only and refuses to pass if any has drifted.

Repository layout

troth/
├── shared-core/    # substrate engine: state, engrams, recall, walls, dispatchers
├── bin/            # CLI router (troth.js) + command modules
├── proxy/          # local provider proxy + dashboard (http://localhost:8000/ui)
├── plugin/         # Claude Code plugin: hooks, skills, 7 MCP servers (4 wired by default)
├── benchmarks/     # reproducible G-series benchmarks + results
├── tests/          # ordered suite + smoke checks + standards
└── docs/           # setup guide, honest limits, MCP host install

Recall stack & model downloads

Semantic recall runs fully on your machine. The first time it's needed,
troth fetches three things into ~/.troth (one time, in the background,
with progress in the logs):

Until they land (or if they never do), recall degrades gracefully to
lexical + whatever is available — nothing breaks, results are just less
sharp. To suppress ALL model/binary downloads (CI, metered networks,
servers): set TROTH_NO_MODEL_FETCH=1 and, to pin your own binary,
TROTH_LLAMA_SERVER_BIN=/path/to/llama-server. Apple Silicon gets Metal
automatically; Intel Macs skip the local stack and stay lexical.

Honest limits

Read docs/HONEST-LIMITS.md before relying on troth. It names what no zero-training stack solves today (conviction under pressure, metacognitive integrity on hard reasoning), what troth actually solves, and how to read the benchmarks without fooling yourself.

License

Copyright (C) 2026 troth. AGPL-3.0-only. See LICENSE for the terms, and LICENSING.md for the parts under other licenses (the plugin/ tree is Apache-2.0) and for the upstream terms attached to models troth downloads at runtime.

TL;DR: use it, fork it, run it commercially. If you host troth as a network service for others, you must offer them the source of your modified version (AGPL section 13); the dashboard links back to this repository for that reason. Private, internal and commercial use is unrestricted.

Contributing

Every commit needs a Signed-off-by: line (DCO). See CONTRIBUTING.md and the code of conduct.

Status

Bootstrap phase. The native macOS app and public launch land at troth.one. Star or watch this repo to follow.