README
¶
You already paid for the answer. Why generate it again to change a sentence?
Questlock helps agents reuse completed work, make checked literal edits without a model, and run bounded tasks through local or hosted models. Add CPU/memory-aware admission and cache-aware SGLang integration when you need them. A Go library and CLI, with a shared SQLite broker underneath.
The mission: lower cost per accepted task, including the work a person has to redo.
Get going
Already use Codex or Claude Code? Install Questlock as a plugin:
Codex / ChatGPT desktop local workflows:
codex plugin marketplace add spfuzzylink/questlock
codex plugin add questlock@questlock
Claude Code:
claude plugin install questlock --marketplace spfuzzylink/questlock
Pick your client, start a fresh chat, and ask it to run the first checked task and repeat it. No provider key or model download is needed. Git installs fetch a pinned, checksum-verified runtime on first use; the offline plugin ZIP already contains it. Setup, offline bundles and recovery.
Prefer the guided setup, including Claude Desktop? Download the matching native archive, then:
./questlock setup
Pick Codex, Claude Code, or Claude Desktop. Setup runs a first task with zero model calls. Codex and Claude Code get guarded configuration and a workflow skill. Desktop gets a native extension bundle to install in its settings. No provider key or model download is needed for that first task.
From a fork or checkout:
./scripts/install.sh
./bin/questlock setup
Already have the binary? questlock try runs just the first task;
questlock doctor --client codex checks local configuration. The broker stays
running for your next request; questlock local stop stops it and keeps your data.
Setup, recovery and all three clients · Source builds and requirements
To run the main coding loop locally, after installing Codex CLI, Ollama and local weights:
./questlock local-agent --model qwen3.5:4b --workspace "$PWD" \
--prompt 'Read the README and list the setup commands.'
Read-only by default, with no imported provider credentials or paid fallback. Local-agent details and quality limits.
What it actually does
| When you need… | Questlock does… |
|---|---|
| The same completed answer | Reuses an exact, explicitly approved task snapshot. |
| A known text or JSON change | Pins the source hash, applies counted edits, checks and publishes the result. No model call. |
| A small new task | Runs a bounded request through local Ollama or a configured provider, with declared checks. |
| Multiple agents on one task | Coordinates claims and rejects stale writes; exact publish retries recover their original receipt. |
| Evidence of a win | Records usage and timing, plus explicit acceptance or later human rework. |
| Repeated writing with changing facts | Combines an approved reference with today's evidence, checks length and keeps a reviewed answer index. |
| Evidence about related questions | Observes possible semantic matches after fresh checked generation, without serving a candidate or avoiding generation. |
| A related question whose answer is still valid | Opt-in controlled reuse checks source provenance, current constraints and a local verifier before serving the saved text. |
| Different wording your app already treats as the same request | An explicit, versioned list maps approved questions to one exact task. No embedding or verifier call. |
Put a local agent team to work on your own machines.
OpenRouter routes the model. Questlock coordinates the work. We build alongside OpenRouter: shared task admission, checked revisions, reusable results and human feedback around your chosen route. An independent companion, with credit to the OpenRouter ecosystem. How they fit.
Local generation has no provider token bill; your machine still does the work. Hosted OpenAI, Claude and OpenRouter calls use their own billing. Only tasks routed through Questlock get these controls. This does not make the surrounding Codex/Claude chat free or remove subscription limits. Measure savings against a matched task baseline, with failed attempts and human rework included.
Different words. Still the same answer?
If your app already knows that “How do I reset my password?” and “Show me the password reset steps” ask for the same thing, it shouldn't need another model to work that out every time.
Give Questlock a small, reviewed list of equivalent questions. The Go helper maps an exact listed wording to one canonical question and a versioned request. The first request runs normally. Later approved forms use the existing exact result while its facts, runtime and expiry still match. No embedding or verifier call is needed for that repeat.
The list is your application's contract. Questlock doesn't guess which new sentences belong in it. A question about losing email access, a different account or a changed policy needs its own facts and request. Unknown wording stays unchanged; your normal configured workflow decides what happens next.
For open-ended paraphrases, controlled reuse remains experimental. Verification can cost more than a fresh answer, and a verifier can miss a change in scope. Keep failed cases in your benchmark too.
Go example, configuration and limits.
Use it with what you already run
Keep your model. Stop repeating work around it. These integrations are opt-in; each one has a different job.
| You use… | What Questlock adds | Sample / setup |
|---|---|---|
| Your Go app | One coordinator for reuse, local admission, shared token quotas and optional telemetry. | Go integration · Configuration examples |
| OpenRouter | Shared task/result reuse around one explicit model/provider route, with adapter fallbacks disabled. | Spec · Route limits |
| OpenAI or Claude API | Bounded text tasks, token-count preflight and optional shared token-price budgets. | OpenAI · Claude |
| Ollama | Bounded local generation using installed weights, plus exact result reuse. | Spec · Local setup |
| SGLang | Deployment identity, cache namespaces and reported KV counters for standalone dense/HiCache tasks. | Spec · GPU setup and limits |
| Langfuse | Opt-in usage/timing traces without prompts or answers. You can see new generation versus reuse. | Export example |
| TypeSafe System One adapter + Ollama | A local label recommendation or abstention; your code keeps control. Uses ordinary Ollama weights, not Jev weights. | Request · Setup |
| Codex / ChatGPT desktop, Claude Code or Claude Desktop | Explicit checked-edit and bounded-task MCP tools inside your client. | Plugins · Guided setup / Desktop MCPB |
| Workers on your own machines | Scoped HTTPS claims and results through one broker, with durable edge sync. | Go example · Deployment |
Show integration code samples
From a checkout, with questlock on your PATH. Start with offline plans:
questlock model plan --spec examples/inference/openrouter-summary.json
questlock model plan --spec examples/model-workflows/openai-handoff.json
questlock model plan --spec examples/model-workflows/claude-handoff.json
questlock model plan --spec examples/model-workflows/local-handoff.json
questlock model plan --spec deploy/sglang/task.json
# Preview setup for an installed client; choose the client you use.
questlock setup --client codex --plan
questlock setup --client claude-code --plan
questlock setup --client claude-desktop --plan
After the linked setup steps, these commands contact your configured services. SGLang inspection generates no answer; the other two commands may run local inference:
questlock model runtime-inspect --spec deploy/sglang/task.json \
--api-base-url http://127.0.0.1:30000
questlock system-one choose --request optional/system-one/reuse.json \
--python /absolute/private/system-one-venv/bin/python
questlock model run --spec examples/model-workflows/local-handoff.json \
--broker http://127.0.0.1:8080 --langfuse --langfuse-timeout 2s
Keep keys in your environment or secret manager. The Langfuse example also needs a broker token and installed Ollama weights. Review the sample facts before a real task; paid runs need current explicit prices and caps. Sample model IDs are examples, not recommendations.
Try before connecting anything
./questlock quest # crashes, stale writes and safe retries
./questlock revise quest # three simple + three complex checked edits
./questlock model quest # shared work and exact result reuse
./questlock outcome quest # acceptance, rejection and human rework
./questlock model runtime-quest # runtime contracts, using HTTP fixtures
./questlock edge quest # durable edge intent and accepted-state sync
./questlock resources quest # bounded queues and pressure-aware admission
./questlock team quest # three scoped HTTPS workers; scripted providers
./questlock semantic quest # shadow observations; simulated embeddings
./questlock semantic reuse-quest # controlled reuse; scripted providers
These demos use temporary state and no model account. Local inference needs installed Ollama weights. Paid generation requires explicit credentials and policy; guided setup enables no paid escalation.
Semantic observation is opt-in and shadow-only. Exact reuse stays first and needs no embedding model. Boundaries and examples.
Controlled answer reuse is a separate opt-in path for read-only questions. Related wording retrieves a candidate; current evidence, source provenance, deterministic guards and a local verifier decide whether the saved answer can serve. Measure correctness and validation overhead on your task. An optional bounded wait can find a peer's finishing answer without interrupting it. The guide includes the Go wiring and explicit local quality-evaluation command.
Keep older work without keeping every payload hot
Questlock can move eligible old content into private, compressed local files while keeping versions, retry receipts, audit history and coordination state. Reads and exact reuse resolve the original bytes without generating them again. Choose a hot-history window such as 30, 90 or 180 days; the default is 90.
Retention is opt-in. Preview with questlock storage archive; --apply moves
content. A configured broker also runs bounded maintenance batches. It deletes
no archive files, and metadata still grows within the configured database page
limit. Policy, limits and operator walkthrough.
Use it from your Go app
Already have a Go app calling a model? Put the work through one
execution.Coordinator for shared result reuse, bounded local admission and
optional Langfuse traces. Keep the provider and model explicit.
coordinator, err := execution.New(ctx, execution.Config{
Runner: inference.Runner{Broker: broker, Provider: provider},
Exporter: langfuse, // optional
})
// Handle err and initial admission readiness; see the complete example below.
result, err := coordinator.Run(ctx, approvedSpec)
A shared scope/day token quota reserves input, output and total tokens before fresh generation. Known usage settles the reservation; uncertain calls keep it. Per-task token limits, call/day dollar caps and local resource settings come from explicit configuration. CPU-only runtimes use the same coordination API.
Complete Go example and configuration · Runnable example · Measured overhead and reuse
Live local check: one generation used 57 input + 20 output tokens; the exact repeat returned the same answer with 0 new tokens and no second generation. The shared quota settled to actual usage; paid fallback stayed disabled.
Local quality evidence
Local teams use explicit JSON types and field roles, bounded reasoning, model release and better macOS memory admission. Wrong answers still stop at the original checks; paid fallback stays disabled.
In the published six-task check, local masters and both reviewers completed the original task contracts. The same saved Codex baseline reports 65,800 hosted tokens; the selected local workflows use 0 hosted tokens and $0 provider API spend. That observation includes five exact case reuses and one fresh three-role run, with extra operator guidance on that case. Whole-chat credit savings and general coding quality remain unmeasured.
Results, failures and limits · Run a local team · Inspect the saved comparison without a model
A real writing check produced 141 words in two paragraphs. Its exact repeat used 0 new model tokens and returned the same answer in 72 ms. The first call took 30.9 seconds, including model loading. Inputs, receipts and what this one observation proves.
Go deeper
- Release notes · Measured build report
- Checked revisions · Bounded delegation
- Model workflows · Acceptance and human rework
- Carry a writing workflow into another chat · Synthetic example
- Langfuse and timings · SGLang/KV cache integration
- Containers · API · Validation
- SecondGate: durable edge push and pull
- Contribute · Security · MIT license · Credits
Experimental. One authoritative broker on one host; no automatic multi-writer replication or demonstrated multi-host scale. The broker controls artifact publication; it does not execute or sandbox agents. See the engineering boundaries.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package admission provides opt-in, single-process resource admission.
|
Package admission provides opt-in, single-process resource admission. |
|
Package client provides a bounded, authenticated HTTP client for Questlock.
|
Package client provides a bounded, authenticated HTTP client for Questlock. |
|
cmd
|
|
|
questlock
command
Questlock is a small, durable publishing gate for cooperating agent workers.
|
Questlock is a small, durable publishing gate for cooperating agent workers. |
|
Package delegation runs an explicit bounded local-first task policy.
|
Package delegation runs an explicit bounded local-first task policy. |
|
Package edge is a bounded durable outbox and read cache for one authoritative Questlock broker.
|
Package edge is a bounded durable outbox and read cache for one authoritative Questlock broker. |
|
Package evaluation compares explicit inference configurations against bounded, deterministic task checks.
|
Package evaluation compares explicit inference configurations against bounded, deterministic task checks. |
|
examples
|
|
|
approved-questions
command
Explicit local-model measurement of caller-approved question forms.
|
Explicit local-model measurement of caller-approved question forms. |
|
edge
command
Run from a source checkout: go run ./examples/edge Downloaded binaries expose the same fixture as questlock edge quest.
|
Run from a source checkout: go run ./examples/edge Downloaded binaries expose the same fixture as questlock edge quest. |
|
execution
command
Run against your own broker and installed local model.
|
Run against your own broker and installed local model. |
|
publish
command
Run against a local broker: QUESTLOCK_TOKEN=...
|
Run against a local broker: QUESTLOCK_TOKEN=... |
|
Package execution composes bounded, process-local admission with the existing shared inference runner.
|
Package execution composes bounded, process-local admission with the existing shared inference runner. |
|
Package inference runs bounded, reusable text-generation jobs through Questlock.
|
Package inference runs bounded, reusable text-generation jobs through Questlock. |
|
internal
|
|
|
agentsetup
Package agentsetup installs the running Questlock executable and embedded workflow skills.
|
Package agentsetup installs the running Questlock executable and embedded workflow skills. |
|
configguard
Package configguard installs complete configuration files through a detached rollback watchdog.
|
Package configguard installs complete configuration files through a detached rollback watchdog. |
|
controlledquest
Package controlledquest exercises the controlled reuse workflow through a real local broker.
|
Package controlledquest exercises the controlled reuse workflow through a real local broker. |
|
desktopbundle
Package desktopbundle creates a self-contained MCPB archive for native installation in Claude Desktop.
|
Package desktopbundle creates a self-contained MCPB archive for native installation in Claude Desktop. |
|
edgequest
Package edgequest exercises real loopback HTTP and private SQLite without a model or an external service.
|
Package edgequest exercises real loopback HTTP and private SQLite without a model or an external service. |
|
httpapi
Package httpapi exposes the storage service through a small authenticated JSON API.
|
Package httpapi exposes the storage service through a small authenticated JSON API. |
|
localruntime
Package localruntime owns one private, loopback broker for local onboarding.
|
Package localruntime owns one private, loopback broker for local onboarding. |
|
nativeagent
Package nativeagent runs bounded text-only roles through an isolated native Codex process backed by already-installed local Ollama weights.
|
Package nativeagent runs bounded text-only roles through an isolated native Codex process backed by already-installed local Ollama weights. |
|
onboardingclient
Package onboardingclient prepares complete assistant settings in a private, isolated home.
|
Package onboardingclient prepares complete assistant settings in a private, isolated home. |
|
semanticquest
Package semanticquest exercises six shadow scenarios through the real broker.
|
Package semanticquest exercises six shadow scenarios through the real broker. |
|
store
Package store provides the single-host storage and authorization boundary.
|
Package store provides the single-host storage and authorization boundary. |
|
teamquest
Package teamquest demonstrates the real broker/claim/check/reuse path with scripted providers.
|
Package teamquest demonstrates the real broker/claim/check/reuse path with scripted providers. |
|
validityeval
Package validityeval contains experimental pair validity diagnostics only.
|
Package validityeval contains experimental pair validity diagnostics only. |
|
Package observability exports bounded execution metadata.
|
Package observability exports bounded execution metadata. |
|
Package outcomes records human acceptance separately from deterministic inference checks.
|
Package outcomes records human acceptance separately from deterministic inference checks. |
|
Package protocol defines the JSON contract between Questlock and its clients.
|
Package protocol defines the JSON contract between Questlock and its clients. |
|
Package retention provides explicit storage policies and an immutable local cold-content store.
|
Package retention provides explicit storage policies and an immutable local cold-content store. |
|
Package revision applies explicitly requested literal edits to pinned text.
|
Package revision applies explicitly requested literal edits to pinned text. |
|
scripts
|
|
|
langfuse-smoke
command
Command langfuse-smoke validates the exporter against a disposable Langfuse v4 server.
|
Command langfuse-smoke validates the exporter against a disposable Langfuse v4 server. |
|
Package semantic observes possible completed-answer reuse.
|
Package semantic observes possible completed-answer reuse. |
|
Package systemone offers an advisory typed choice using the official TypeSafe adapter and explicitly selected local Ollama weights.
|
Package systemone offers an advisory typed choice using the official TypeSafe adapter and explicitly selected local Ollama weights. |
|
Package team coordinates bounded local master/reviewer tasks through one authoritative broker.
|
Package team coordinates bounded local master/reviewer tasks through one authoritative broker. |
|
Package worker exposes bounded explicit delegation through MCP over stdio.
|
Package worker exposes bounded explicit delegation through MCP over stdio. |
|
Package writing builds explicit, local-only prose snapshots and keeps a content-free index of reviewed answers.
|
Package writing builds explicit, local-only prose snapshots and keeps a content-free index of reviewed answers. |