Effortlessly build efficient model-, task-, or domain-specific harnesses.
Web app: web.deepclause.ai
Follow us on X (@hilbertshelper) · Blog: deepclause.substack.com
DeepClause is a Prolog-based runtime for self-modifying agent harnesses. A harness created with DeepClause is a self contained library in the form of a DML module. DML (DeepClause Meta Language) is a Prolog DSL with added functionality for LLM model calls, semantic judgments (Jev-type models), and constraints. An LLM agent embedded in the runtime reads, extends, and tests code in a live module a turn by turn. You drive it from an interactive REPL. Using the REPL once can successively build a custom harness that is optimized for a specific use case.
DML runs on SWI-Prolog compiled to WebAssembly — the whole language runtime is in-process and portable, with no native Prolog to install.
Most agent stacks contain a lot of separate moving parts: tools in one place, prompts in another, memory in a third, and the workflow as a graph or a chain somewhere else. DML folds them into one idea — a predicate. A skill is a clause, a tool is a clause, memory and state are clauses, control flow and retries are clause order and backtracking, and a workflow is simply predicates calling predicates. Because it is one language in one self-contained file, the parts can read, reuse, and extend one another, and a whole harness can be inspected, versioned, and moved as a unit.
That shape pays off most when a capability is specific. Because a harness is a
single module you can edit, diff, and version — and because the REPL lets an
authoring agent grow it by talking — it is unusually cheap to build one tuned to
a particular model (its prompt style, context budget, reasoning level), a
particular task, or a particular domain. The same file can also route
individual calls across several models with with_model/2: a cheap model for
classification, a strong one for the hard step, all decided in plain Prolog.
Dependencies and acknowledgements
DeepClause stands on other people's work, and is grateful for it:
- Pi (
@earendil-works/pi-coding-agentand@earendil-works/pi-ai) — thepibackend reuses Pi's model catalog, credential store, streaming, cancellation, and usage accounting, and the interactive REPL TUI is built on Pi's terminal UI library (@earendil-works/pi-tui). Thanks to the Pi developers for building and sharing it. - SWI-Prolog — the Prolog engine that DML runs on, compiled to WebAssembly so the whole runtime is in-process and portable. SWI-Prolog is created and maintained by Jan Wielemaker and the SWI-Prolog community.
- Markus Triska — his work on
meta-interpreters, constraint logic programming, and the
library(clpfd)/library(clpq)libraries underpins DML's executable meta-interpreter and constraint layer.
DML, the REPL, and the SDK are original work; these projects are used as dependencies and as conceptual foundations.
Why would I use this?
- Reproducibility. Control flow, retries, and validation are Prolog clauses you can read and re-run, so a DML harness tends to produce the same result shape across sessions and machines. The model is consulted only at the points you choose, and its outputs are typed where that helps.
- Auditability. Each turn is a transaction: the module is snapshotted, the change is committed replace-by-predicate, and the session, event trace, and harness versions are recorded and remain queryable. It is possible to see what changed, when, and in response to what.
- Regulated and high-stakes settings. Where a workflow has to be reviewed,
versioned, and reproduced — and where it helps to keep deterministic logic
separate from model judgment — a small, inspectable harness is easier to
scrutinise than a prompt. The transaction record and
rollback.are meant to support that kind of review, not replace it. - Research in neurosymbolic AI. DML offers a concrete substrate for combining symbolic reasoning (Prolog, CLP, backtracking) with LLM calls and semantic judgments in one program, and for studying how such a system behaves as an agent edits it over time (transactions, history, rollback).
It is likely not worth it when a single prompt or a short script is enough, or when there is no structure you would want to reuse, review, or reproduce.
Develop and Work
DeepClause has two ways to use the same harness:
| Develop | Work | |
|---|---|---|
| Purpose | Author and edit the harness | Use the harness |
| Input | plain English, or /goal <dml> |
chat with the declared tools, or run a declared workflow |
| Can change DML | yes, through transactional commits | no |
Needs shell/1 |
no | yes |
Develop is the default. Describe a skill, tool, or change in plain English; the authoring agent writes, tests, and commits it. Work is the stable, non-authoring surface for a harness that is ready to use.
Work needs a shell
A harness becomes usable in Work when it declares a shell/1 fact:
shell(_{ kind: agent, system: "You are a concise writing assistant.", host_tools: [], tools: [ _{name: "text_length", goal: "length_of", description: "Count characters in text.", inputs: [_{name: "Text", type: string}], outputs: [_{name: "N", type: integer}]} ], workflows: [ _{name: "Uppercase", goal: "uppercase", inputs: [_{name: "Text", type: string}], outputs: [_{name: "Upper", type: string}]} ], welcome: "Ask about text, or choose Uppercase." }).
kind: agentgives a chat assistant that can call only the declared tools and workflows.kind: workflowgives a workflow-only surface with no assistant.toolsare declared DML tools;host_toolslists host capabilities the harness may use (for examplebash). Host grants and sandbox boundaries still apply.- Workflow inputs and outputs are typed. Missing or invalid inputs fail before execution; a failed, cancelled, or suspended workflow is not success.
- A harness without
shell/1has no Work interface. Open Develop or an explicit Run instead.
Entering Work
In the TUI:
/mode work [harness] open a Work conversation
/workflows list declared workflows
/workflow "Uppercase" {"Text":"hello"} run exactly that workflow
/mode develop [harness] return to authoring
From the CLI (assuming a harness named example):
deepclause repl --mode work --harness example deepclause repl --mode work --harness example \ --workflow "Uppercase" --inputs '{"Text":"hello"}' --json
A manual --workflow run executes exactly that workflow and makes zero
assistant calls. An agent shell calls the model only when the conversation
needs it. Work and Develop are separate conversations with separate snapshots.
Work is pinned to the harness version it started with; to change the shell,
tools, or workflows, return to Develop (or open a fresh Work conversation after
the edit).
See Work mode for the full contract and TUI/web reconciliation for implementation status.
The REPL: a living, self-modifying harness
In default Develop mode, the REPL keeps a persistent DML module ("the harness"). You talk to it in two ways:
| Input | Mode |
|---|---|
<plain English> (default) |
author — the agent writes, tests, and commits DML |
/goal <dml> |
run — query the current harness |
dml> add a research(Question, Answer) skill that answers with task/2 and cites sources
dml> run research on "why is the sky blue?"
A = "Rayleigh scattering scatters short wavelengths more strongly..."
dml> /goal research("why is the sky blue?", A). % the same skill, run directly
The default mode is the interesting one: describe what you want and the authoring agent edits the module for you through tools, testing as it goes. Ask for anything — add a skill, add a tool, change existing logic, run or test code in the living module, or just ask a question about the harness.
A worked session
A full pass: create a skill, watch the transaction, run it, export it, and load it again as a new harness.
1. Create (one transaction)
dml> add a research(Question, Answer) skill that answers with task/2
⚙ begin_turn
✔ begin_turn · 2ms
⚙ assert_many(clauses=module_doc("…"), research(Question, Answer) :- task(…), doc(research/2, …))
✔ assert_many · 11ms
⚙ execute
research("Why is the sky blue?", A).
▸ Task Answer this research question: Why is the sky blue?
✔ Task done
A = "Rayleigh scattering…"
✔ execute · 3.7s
⚙ end_turn(summary=Add research/2)
✔ end_turn · 4ms — {"committed":true,"changed":["+research/2","+module_doc/1","+doc/2"]}
Added research/2 — a one-call task/2 research skill.
The agent opened a transaction (begin_turn), wrote the predicates
(assert_many), tested them with execute, and committed with end_turn — which
printed the predicates it changed and recorded a version. Had the turn failed,
the host would have rolled the module back to exactly its prior state.
2. Inspect, run, undo
dml> /listing
skill: Research a question and return a written answer.
doc/2
doc(research/2,"Answer a question in one model call. research(+Question, -Answer). …").
module_doc/1
module_doc("Research a question and return a written answer. …").
research/2
research(A,B) :-
task("Answer this question: {A}",B).
dml> /goal research("Why is the sky blue?", A).
A = "Rayleigh scattering…"
dml> /rollback
rolled back harness: version 1 → 0
dml> /goal research("Why is the sky blue?", A).
false. % the skill is gone
end_turn is the only commit point, and /rollback moves the harness back one
committed version (here, to the baseline) — so nothing is committed silently.
3. Export
dml> /export research.dml
exported 3 clauses, 0 tools, 0 scripts → research.dml
research.dml is a plain DML file: commit it, diff it, mail it. Use a .zip
target to bundle linked script_file/2 scripts.
4. Load it elsewhere (a harness from somewhere else)
deepclause repl -l research.dml
Loading a file targets the harness named after it (research), creating it if
needed. The file becomes that harness's baseline, so it works with no prior
history: /rollback floors at the loaded file, never at empty.
5. Several harnesses in one project
deepclause repl # harness `main` deepclause repl --harness support # harness `support` deepclause repl -l research.dml # harness `research`
Each harness has its own content and version history under
.deepclause/repl/harnesses/<name>/. A fresh session loads its harness's current
content (the agent continues what is there instead of re-creating it), and
/rollback never crosses harnesses.
Example: build a coding agent
You can ask for a whole capability, not just a one-off answer:
dml> build me a coding agent harness for this repo
⚙ listing
✔ listing · 1ms
⚙ begin_turn
✔ begin_turn · 2ms
⚙ define(head=run_shell(Command, Output), clauses=run_shell(Command, Output) :- exec(bash(…), Result), …)
✔ define · 31ms
⚙ define(head=fs_read(Path, Text), clauses=fs_read(Path, Text) :- read_file(Path, Text).)
✔ define · 6ms
⚙ define(head=fs_write(Path, Content), clauses=fs_write(Path, Content) :- write_file(Path, Content).)
✔ define · 5ms
⚙ define(head=fs_grep(Pattern, Path, Matches), clauses=fs_grep(Pattern, Path, Matches) :- …)
✔ define · 7ms
⚙ assert_many(clauses=tool(run_shell(…)) :- run_shell(…). tool(fs_read(…)) :- …. …)
✔ assert_many · 4ms
⚙ define(head=explain(Question, Answer), clauses=explain(Question, Answer) :- system(…), with_tools(…).)
✔ define · 8ms
⚙ define(head=patch(File, Issue, Summary), clauses=patch(File, Issue, Summary) :- system(…), with_tools(…).)
✔ define · 9ms
⚙ execute
fs_read("package.json", T), run_shell("npm test", R).
✔ execute · 1.4s
⚙ end_turn(summary=Add coding-agent skills: run_shell/fs_read/fs_write/fs_grep + explain/patch)
✔ end_turn · 12ms — {"committed":true,"changed":["+run_shell/2","+fs_read/2","+fs_write/2","+fs_grep/3","+explain/2","+patch/3"]}
A coding-agent harness is ready: a small shell/file toolset exposed to `task/N`, plus
`explain/2` and `patch/3` skills that scope those tools per task.
The harness it built (trimmed):
module_doc("Coding agent: read, search, and edit a repository and run its tests."). run_shell(Command, Output) :- exec(bash(command: Command), Result), ( get_dict(stdout, Result, Out) -> Output = Out ; Output = "" ). fs_read(Path, Text) :- read_file(Path, Text). fs_write(Path, Content) :- write_file(Path, Content). fs_grep(Pattern, Path, Matches) :- format(atom(Cmd), "grep -rn -- ~w ~w", [Pattern, Path]), exec(bash(command: Cmd), Result), ( get_dict(stdout, Result, Out) -> Matches = Out ; Matches = "" ). % `tool/2` only exposes the predicates above to the nested agent in task/N. tool(run_shell(Command, Output), "Run a shell command; returns stdout.") :- run_shell(Command, Output). tool(fs_read(Path, Text), "Read a workspace file.") :- fs_read(Path, Text). tool(fs_write(Path, Content), "Write a workspace file.") :- fs_write(Path, Content). tool(fs_grep(Pattern, Path, Matches), "Search a path; returns matching lines.") :- fs_grep(Pattern, Path, Matches). doc(explain/2, "Explain code relevant to a question. explain(+Question, -Answer)."). explain(Question, Answer) :- system("You are a coding assistant working in a repository. Cite file paths and line numbers."), with_tools([run_shell, fs_read, fs_grep], task("Answer this question about the repository: {Question}", Answer)). doc(patch/3, "Apply a minimal fix and run the tests. patch(+File, +Issue, -Summary)."). patch(File, Issue, Summary) :- system("Make the smallest change that fixes the issue. Run the project's tests and report the result."), with_tools([run_shell, fs_read, fs_write, fs_grep], task("Fix this issue in {File}: {Issue}. Then run the tests and report what changed.", Summary)).
Use it:
dml> /goal explain("where are the CLI entry points?", A).
A = "…"
dml> /goal patch("src/cli.ts", "the --help flag is missing", S).
S = "…"
dml> /export coding_agent.dml
deepclause repl -l coding_agent.dml # harness `coding_agent` deepclause run coding_agent.dml --goal 'explain("…", A)' # one-shot
Notes:
tool/2is only an annotation; the capabilities are the predicates above, so they are reachable fromexecute//goaland fromtask/N.with_tools/2scopes which tools atask/Nturn may call —explaincannot edit files,patchcan.- Because a
task/Nturn can call these tools (and itself), the module is an RLM-style harness, not a fixed script.
Model switching
A harness can choose the model for individual calls with with_model/2, so you
can route cheap work to a small model and hard work to a strong one — or tune a
whole harness to one model:
% a cheap model for classification triage(Message, Team) :- with_model("openai:gpt-4o-mini", prompt("Classify as billing/orders/account: {Message}", Team)). % a strong model at high reasoning, only for the hard step review(Diff, Notes) :- with_model("anthropic:claude-sonnet-4#high", task("Review this diff and list defects:\n{Diff}", Notes)). % full control via a dict with_model(model{provider: "google", id: "gemini-2.5-pro", temperature: 0.2, maxTokens: 8192}, Goal).
with_model scopes the task/N, prompt/N and sample_token/N calls inside
Goal (judgments keep their own backend); the innermost scope wins, and it
composes with with_reasoning/2. The models available to a session are the
credentialed ones from pi's catalog, each shown to the authoring agent with
its price (USD per 1M tokens, in/out) so it can pick the cheapest model that
fits — call the models tool for the live list. An unknown or unsigned-in model
fails with a clear error.
Sessions
The REPL also records sessions, turns, and harness versions under
.deepclause/repl/, so you can pick a conversation back up later. Its harness,
conversation memory, and turn count are restored:
deepclause repl --session last # resume the most recent session deepclause repl --session repl_m9x1_1 # …or one by id
A turn can also suspend itself at a safe point and be continued on resume — the continuation is a goal, so the program says where it is safe:
loop(N) :- ( N >= 2 -> suspend(loop(N)) % stop here; resume with loop(N) ; M is N + 1, loop(M) ).
suspend/1 refuses while the turn holds something a snapshot cannot carry — an
open stream or an open form — so a resumed session never inherits a half-written
file. See docs/DML_REPL_SUSPEND_RESUME.md.
Why Prolog/DML for a self-modifying harness
An RLM-style harness works best when the harness is the program the model edits. DML makes that literal:
- The harness is data = code. Skills are predicates, data is facts
(
city(ch, "Zürich").). The model reads it (listing), queries it (/goal), extends it, and reuses it — no separate plugin format and no recompile step. - One language for logic and language. Recursion, backtracking, and CLP
constraints sit next to LLM calls (
task/N) and typed semantic judgments (choose,verify,rate,probability) in the same clause. - Composable skills. A
task/Ncall runs a bounded agentic turn that may itself call other skills, so the library grows by composition and reuse. - Small and inspectable. Everything a harness can do is visible in the
module and the host tool catalog (by default
bash, plus the human-in-the-loopask_user/input/2).
Transactions
A prompt turn is an edit transaction:
- the living module is snapshotted;
- the authoring agent edits predicates with tools (
define/assert/assert_many/retract/delete) and tests them withexecute; end_turnvalidates and commits the change, recording a version;rollback— or a failed turn — restores the harness unchanged.
For anything larger than a couple of predicates the agent is instructed to commit
working pieces as it goes (execute → end_turn → begin_turn), so a late
failure does not lose earlier progress.
Auditability
Every session, turn, event trace, and harness version is written under
.deepclause/repl/ — per harness under harnesses/<name>/ (harness.dml,
baseline.dml, HEAD.json, changes.jsonl, versions/) — and exposed to DML
as queryable harness_* facts (harness_session/5, harness_turn/5,
harness_change/5, harness_changed/4, harness_head/4, harness_trace/3).
rollback. restores the previous version, step by step, and a harness can query
its own past:
recent_changes(N, Changes) :- findall(Version-Timestamp, harness_change(Version, Timestamp, commit, _, _), All), last_n(All, N, Changes).
See docs/REPL.md and
docs/DML_REPL_SESSION_HISTORY.md.
Commands
/goal <dml>, /listing [filter], /viz [entry] [--spec], /show <path>,
/gen <prompt>, /spawn <goal> (/serve), /ps [--watch|--logs|--code],
/send <name> <term> (/cast), /call <name> <term>, /stop <name>,
/model [id], /reasoning [level], /show-reasoning [mode],
/harness [width], /login, /help, /reset, /rollback, /compact [notes],
/export [file], /freeze//unfreeze, /params, /trace//notrace,
/halt (aliases /exit, /quit). The legacy goal:/listing. dotted forms
still work.
Subagents and concurrency
The REPL can run subagents: session-scoped DML processes that keep running
after the turn that started them, talk to each other by messages, and run in
parallel. Start one with /spawn, watch them with /ps --watch --logs, and
message them with /send / /call:
dml> /spawn debate("Nuclear power should expand", 2)
spawned proc(main, sess_abc, p1)
dml> /ps --watch --logs
──────────────────────────────────────────────
⚙ services — 2 processes · 2 active · debater running · debater running
──────────────────────────────────────────────
debater PRO opening: the evidence supports setting a price…
debater CON (round 2): a price is regressive without a rebate…
debater ✓ set_result
debater › finished
The authoring agent uses the same machinery through its ps / send / stop /
swarm / wait tools, and drives spawn and request/reply through execute
with the DML built-ins (spawn, send/receive, serve/service_call,
swarm/pmap). A
subagent runs against a private snapshot of the module with value
semantics — a result comes back by message, never by a shared variable — which
is what makes it safe to run many at once.
Execution has two modes: --execution worker (the default; a worker thread with
its own WASM — true parallelism and hard cancellation) and --execution inline
(cooperative, in-process). The same DML runs unchanged.
See docs/SUBAGENTS.md for the model, the surface, the
Erlang/BEAM inspiration, and the L1/L2 seam.
Install
npm install deepclause-sdk
Quick start
deepclause init # write .deepclause/config.json deepclause login # sign in to provider, then pick a model deepclause repl # interactive deepclause repl --session last # resume the most recent session deepclause run skill.dml "arg" # one-shot
Backends
pi is the default: it reuses pi's model catalog and credential store. env
uses the SDK's own provider/API keys.
deepclause login [--provider <id>] [--api-key <key>|--oauth] [--model provider/model] [--thinking <level>] deepclause logout [provider] deepclause set-backend status deepclause set-backend env # switch to provider API keys
For reasoning-capable models, deepclause login/set-backend/set-model prompt
for a thinking level (off|minimal|low|medium|high|xhigh|max); pass --thinking
to skip the picker. It is stored as backend.thinkingLevel and forwarded to pi
only for models that support it.
Credentials live in pi's agent dir (~/.pi/agent) unless backend.agentDir
overrides it. Existing pi installations stay untouched.
Local models (Ollama, llama.cpp, vLLM)
llama.cpp (router or single-model)
When llama-server runs in router mode (started without --model or -m),
the pi backend registers pi's built-in llama.cpp provider and discovers its
models live. Point it at the router with LLAMA_BASE_URL, or sign in once:
# one-off / environment-driven export LLAMA_BASE_URL=http://127.0.0.1:8080 deepclause repl # or persist the router URL + an optional API key and pick a default model deepclause login --provider llama.cpp # non-default host and port deepclause login --provider llama.cpp --host 192.168.1.50 --port 9000 deepclause login --provider llama.cpp --base-url http://gpu-box:9000 deepclause set-backend pi --provider llama.cpp --host 192.168.1.50 --port 9000 \ --model llama.cpp/<id>
--base-url wins over --host/--port; a bare --host defaults the port to
8080, and --port alone defaults the host to 127.0.0.1. Passing an explicit
endpoint re-runs the login, so the stored router URL is updated. The interactive
login prompt also accepts a full URL, a bare host, or host:port when these
flags are omitted, and --provider llama.cpp may be omitted when one of these
endpoint flags is present. For a router that requires an API key, add
--api-key <key>; the URL is resolved from the explicit flags, then
LLAMA_BASE_URL, then http://127.0.0.1:8080.
Inside the REPL, /login lists llama.cpp. Selecting it prompts for a base
URL, a host:port, or a host and then a port. You can also pass the endpoint
directly:
/login llama.cpp --host 192.168.1.50 --port 9000
/login --base-url http://gpu-box:9000
After /login, /model includes the models discovered by that login (the
choice still applies on the next start). Use /model llama.cpp/<id> to set the
default, or pass --model llama.cpp/<id> for this run. Start the router with
--jinja when you need tool calling for task/N.
Single-model mode also works: when /models does not return router metadata,
DeepClause falls back to /v1/models and registers the reported model. If the
server exposes neither a model id nor a model path, it uses the placeholder id
local-model. Use models.json if you need to pin an exact id for a server
that rejects arbitrary model names.
Other OpenAI-compatible endpoints (Ollama, vLLM)
The default pi backend reads pi's models.json, which can declare custom
OpenAI-compatible providers, so a local server needs no SDK changes:
deepclause set-backend pi --list # lists "loc (Local server) — configured [api-key]" # and the model "loc/llama3.1" deepclause repl --model loc:llama3.1
run has no --model flag; set backend.model instead. DML can route a single
step there as well — with_model("loc:llama3.1", Goal).
Point at a non-default file with backend.modelsPath in
.deepclause/config.json (or PI_CODING_AGENT_DIR to move pi's whole agent
dir), which keeps a project's catalog in the repository rather than the home
directory:
{ "backend": { "kind": "pi", "model": "loc:llama3.1", "modelsPath": "./agent/models.json" } }apipicks the wire protocol.openai-completionsis what Ollama, llama.cpp, vLLM and SGLang serve;openai-responsesis the newer OpenAI API. Per-providercompatflags cover servers that differ (maxTokensField,supportsUsageInStreaming,requiresToolResultName, …), and a model'ssamplingParamsforwardstop_p/top_k/repetition_penalty.- Tool calling is required for
task/N, which ends by callingset_result/finish; a text-only model exhausts the turn instead.chat/1needs no tools, so a small local model is usable there, or pick a model whose chat template supports tools. list-modelsprints the bundled model database and will not show custom entries;set-backend pi --listprints pi's catalog, which does.- The
envbackend can also point at a local server (providers.openai.baseUrl+apiKey), but it always speaks chat completions andreplignoresproviders.*.baseUrltoday — prefer thepibackend.
run
run uses the same engine as the REPL: it opens a module, loads the
DML file (.dml or a .zip bundle), runs one entry, and renders events through
the REPL renderer. The entry is agent_main/N (chosen by the number of
positional arguments) or an explicit --goal.
deepclause run <file.dml> [args...] # call agent_main/N deepclause run <file.dml> --goal '<dml>' # explicit entry goal deepclause run <file.dml> --dry-run # print the resolved entry deepclause run <file.dml> --trace t.json --usage u.json deepclause run <file.dml> --no-stream --no-events # only outputs/answers
Runtime and sandboxing
Engine. DML is executed by SWI-Prolog compiled to WebAssembly
(vendor/swipl-wasm, loaded through src/prolog/). It runs in-process — no
native Prolog install, no external server — with the standard SWI libraries
available (constraint solving via clpfd, clpq, clpr; plus regex, dicts,
and DCGs). Validation runs on the same engine.
Workspace confinement. DML file predicates and bash all run against the
active workspace (. or --workspace <path>) using workspace-relative
paths; harness paths cannot escape it.
Shell execution. bash is the only capability tool, with two backends:
| Backend | When | Notes |
|---|---|---|
| host shell | default | isolated by a wrapper: clean-room, bwrap (bubblewrap), or sandbox-exec (macOS); auto picks the best available |
| AgentVM | --sandbox |
WASM micro-VM; network disabled by default |
Network access is off by default (agentvm.network: false), and bwrap
with shell.strictIsolation: true also disables it. --no-tools registers no
capability tool at all; ask_user / input/2 remain the human-in-the-loop
channel.
deepclause repl --sandbox # run bash inside the AgentVM micro-VM deepclause repl --no-tools # no capability host tools
{
"agentvm": { "network": false },
"shell": { "wrapper": "auto", "strictIsolation": false }
}visualize
Turn a harness into a diagram: visualize reads the harness listing
(source + doc/2 annotations) and asks the active model for a Mermaid chart of
one entry, then renders it.
deepclause visualize skill.dml -g router/2 --presentation -o router.png deepclause visualize skill.dml -g router/2 --spec -o router.spec.svg deepclause visualize skill.dml -g router/2 --ascii
-g/--goal names the entry predicate to document. --presentation (default) is
an audience-facing overview (inputs, steps, answer); --spec shows engineering
detail (decisions, task/exec calls, branches, fallbacks). A .mmd output
writes the Mermaid source; .svg/.png render it without a browser (SVG is
generated directly, PNG via the bundled @resvg/resvg-js rasterizer), and the
.mmd is always written beside the image. --ascii prints a terminal-friendly
Unicode tree instead of a file.
In the REPL, /viz [entry] [--spec] draws a skill inline: on Kitty/Ghostty/
WezTerm/iTerm2 it emits an inline image (through pi-tui's terminal-image encoder);
on other terminals it falls back to the ASCII tree. Force a renderer with
/viz --graphics=kitty|iterm2|ascii|off. The authoring agent's visualize tool
uses the same path, so "visualize this harness" paints the image too (and
falls back to the ASCII tree on terminals without image support).
Media (images)
Images are workspace files referenced by a media(Path, Mime) term; the bytes
never enter Prolog or conversation memory. Read a reference and attach it, and the
next task/N sends it to a vision-capable model:
agent_main :- read_media("photos/fox.png", Image), attach_media(Image), task("Describe the image in one sentence.", Description), answer(Description).
Only PNG/JPEG/GIF/WebP/SVG are accepted, and judgments stay text-only.
Images can also be displayed and generated:
output(media("charts/plot.png")). % show an image inline (kitty/iTerm2) task("a red fox in snow", media(Img)), % generate → Img = "…/image-….png" output(media(Img)). % …and show it
output(media{svg: Svg}) shows inline SVG; save_image(Media, "out.svg")
persists a reference. On other terminals the path is printed (and opened with
xdg-open/open), and --json emits a media event with base64 PNG data. In
the REPL: /show <path> and /gen <prompt>. See docs/DML_MEDIA.md.
TypeScript SDK
import { createDeepClause } from 'deepclause-sdk'; const dc = await createDeepClause({ model: 'gpt-4o', provider: 'openai' }); for await (const event of dc.runDML(dmlSource, { args: ['topic'] })) { if (event.type === 'answer') console.log(event.answer ?? event.content); } await dc.dispose();
To reuse pi's model and credentials from a host, pass an injected LLMBackend
(createPiBackend) and judgment backends (createLLMJudgeBackend,
createJevJudgeBackend).
The REPL is embeddable too:
import { createHarnessRepl } from 'deepclause-sdk'; const repl = await createHarnessRepl({ model: 'gpt-4o', provider: 'openai' }); for await (const event of repl.query('fact(5, F)')) { if (event.type === 'solution') console.log(event.solution?.bindings); } await repl.dispose();
Validation
import { validateWithProlog } from 'deepclause-sdk/validate'; const { valid, errors, warnings } = await validateWithProlog(dmlSource);
Configuration
.deepclause/config.json (created by init):
{
"backend": { "kind": "pi", "model": "anthropic/claude-sonnet-4" },
"temperatures": { "run": 0.7 },
"providers": { "openai": { "apiKey": "..." } },
"agentvm": { "network": false },
"shell": { "wrapper": "auto", "strictIsolation": false, "timeoutMs": 0, "idleTimeoutMs": 180000 },
"repl": {
"tui": "auto",
"harness": "main",
"showReasoning": "summary",
"maxModelCalls": 100,
"compaction": { "enabled": true, "auto": true },
"media": { "dir": ".deepclause/media", "open": true, "inlineJson": true, "imageModel": "openai:gpt-image-1" },
"history": { "enabled": true, "dir": ".deepclause/repl", "trace": "summary" }
},
"judgment": { "default": "llm", "jev": { "enabled": false } }
}Repository layout
src/
├── repl/ # living-module REPL (session, agent, render, history, media,
│ # processes, process-executor, worker-host, models)
├── cli/ # init, run, repl, login, set-backend, visualize
├── visualize/ # diagrams: Mermaid → Unicode tree / SVG / PNG + terminal graphics
├── system/ # shell/AgentVM, config, model database + catalog, bundled docs
├── judge/ # semantic judgment backends (llm, jev, mock)
├── prolog/ # SWI-Prolog-WASM loader/bridge
├── prolog-src/ # deepclause_mi.pl, deepclause_analysis.pl, …
├── agent.ts # task/agent loop
├── runner.ts # DML execution
├── sdk.ts # createDeepClause
└── validate.ts # DML validation/linting
vendor/
└── swipl-wasm/ # SWI-Prolog compiled to WebAssembly (the DML engine)
Bundled prompt assets: AGENT_PROMPT.md (the authoring agent's contract),
DML_REFERENCE.md (language), DML_AUTHORING.md (guide),
HARNESS_EXAMPLES.md (idiomatic shapes), HARNESS_PATTERNS.md (harness shapes
by use case), PROLOG_SNIPPETS.md (tested building blocks).
Development
npm run build # tsc + copy prolog + assets npm test # vitest npm run repl # deepclause repl via tsx
npm run build is required for the default process backend. L2 (worker)
processes run dist/repl/process-worker.js, so editing src without rebuilding
runs old worker code against a new main — the symptom used to be child sessions
that silently had no harness. WORKER_PROTOCOL_VERSION now fails that loudly
(stale L2 process worker: … run 'npm run build'). The tests that need it
(repl-process-worker-child) skip themselves when dist is absent.
See docs/: SUBAGENTS.md (subagents and
concurrency), STATUS.md (current state),
REPL.md,
DML_REPL_PROPOSAL.md,
DML_REPL_SESSION_HISTORY.md,
DML_MEDIA.md,
DML_MODEL_SWITCHING.md,
DML_REPL_WORKER_EXECUTION.md (plan),
DML_FORMS.md (structured human input),
JUDGMENT_BACKENDS.md.
License
MIT
