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 delegate small tasks to a local model. 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
Download and extract the matching v0.9.1 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. |
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.
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
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.
New in 0.9.1
Local teams get 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.
The six original task contracts now complete with checked local masters and both reviewers. 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
Go deeper
- What changed in 0.9.1 · Measured build report
- Checked revisions · Bounded delegation
- Model workflows · Acceptance and human rework
- 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
|
|
|
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. |
|
publish
command
Run against a local broker: QUESTLOCK_TOKEN=...
|
Run against a local broker: QUESTLOCK_TOKEN=... |
|
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. |
|
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. |
|
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. |
|
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 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 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. |