lictor is an autolith-style terminal agent for the Exsecutor compiler
project, driven by the operator's own local Claude Code binary rather than
a direct Anthropic API key. It runs on the Claude Agent SDK, which launches
that binary as a subprocess, so inference rides the same subscription
login claude already uses on this machine -- lictor never calls the
Anthropic API directly. What makes it autolith-like, rather than just
another chat loop with some repo-specific tools bolted on, is self.*:
a live, self-modifying image with a redefine → exercise → commit →
generation → rollback pipeline, so a running session can change its own
behavior durably, under a replay-probed, git-backed safety net, without
ever touching lictor's real source tree except through an explicit,
separate step.
An interactive session is a REPL, but one where the default input is prose:
a line that is not a /command, a !-form, or a line beginning with a
literal space is sent to Claude as a user turn, exactly as typed. /commands
drive the session itself (/status, /model, /effort, /mode,
/resume, /generations, /rollback, /vault, /tools, and more --
/help lists what the running build has wired up). A !expr line, or a
!! ... !! block, evaluates Python directly in the live image's own
namespace (prompt, read_file, state, cfg, registry, apropos,
and -- once self.* has redefined something -- whatever that redefined).
Beyond Claude Code's own built-in tools (Read, Edit, Bash, and so on,
fenced to the active git worktree by lictor's own hooks), lictor registers
five tool namespaces, each its own in-process MCP server because an Agent
SDK tool name cannot contain a dot (docs/architecture.md explains why):
exs.*-- gated, journalled entry points into the Exsecutor workspace's own build/test/spec tooling:exs.build,exs.test,exs.spec_check,exs.audit,exs.conformance,exs.spec(section),exs.codes(query),exs.worktree(op, name), and friends. Every subprocess-backed one runs bounded, in its own process group, with the full output spilled to an artifact file and a non-zero exit reported as data, never raised.self.*-- inspects and redefines lictor's own running image:status,describe,redefine,diff,exercise,discard,commit,persist_definition,set,apropos. See
docs/mutations.md for the full pipeline.
py.*-- isolated, persistent Python worker REPLs in separate OS processes that import nothing from lictor itself (docs/architecture.md, "the boundary that matters"):eval,start,stop,repls,reset.rlm.*-- a bounded sub-inference over context the operator names, with an optional JSON schema for structured output:infer,map,complete.resource.*--resource.read(uri)over four schemes:workspace:<relpath>,inference:<trace-id>,session:<cid>,vault:current.
Programmatic subagent roles (lictor/roles.py) load from Markdown
front-matter files and are passed to the SDK as ClaudeAgentOptions(agents= ...), reachable from a turn via !prompt("...", to="role-name"). Two
example roles ship, documented rather than auto-loaded, under
lictor/prompts/roles/ -- spec-guardian.md (read-only, checks a claim
against the spec and the §13 registry) and fixture.md (writes one
conformance fixture and confirms it fails with its exact intended code) --
copy either into <config>/agents/ or <workspace>/.lictor/agents/ to
actually load it.
Install and run via the flake:
nix build .#default
./result/bin/lictor --version
./result/bin/lictorTwo of those three are measured rather than asserted. The build and the
version print are gated claims; the bare lictor needs a terminal, so it
is shown, not checked.
python -m lictor --versionpytest -qlictor --once "some prose" runs exactly one turn non-interactively and
exits with the turn's is_error as the process exit code -- useful for
scripting or for the sort of sanity check this README's own Evidence
section below is built from. With no --once, it opens the interactive
REPL described above.
lictor --recovery forces a recovery boot: no overlay replay, no
workspace init.py, and the startup banner surfaces the most recent crash
report if there is one. The same thing happens automatically, without the
flag, if the previous process's boot.json was still in
phase: "starting" when this one started -- the signature of a crash
during startup, answered by not repeating whatever just failed.
--force overrides lictor's refusal to start at all when
CLAUDE_CODE_MESSAGING_SOCKET is set in the environment -- the signature
of already being inside a running Claude Code session. An SDK-driven agent
nested inside another Claude Code session is unsupported: lictor's own
options.scrub_environ removes every CLAUDE_CODE_* variable (keeping
only CLAUDE_CODE_OAUTH_TOKEN and CLAUDE_CONFIG_DIR) before the SDK is
ever imported, precisely so the subprocess it launches does not inherit
state from an outer session -- but starting lictor from inside one in
the first place is a configuration nobody has verified behaves sanely, so
it is refused by default rather than silently tolerated. --force exists
for exactly the cases where an operator has decided that risk is theirs to
take.
lictor --ollama MODEL (or [ollama] enabled = true, model = "..." in
config.toml) points the claude binary at an Ollama server instead of
the subscription login: ANTHROPIC_BASE_URL is set to the Ollama host
(default http://localhost:11434, [ollama].host), ANTHROPIC_API_KEY
is emptied, and every model alias (opus, sonnet, haiku, so rlm.*
and role files too) resolves to the one Ollama model. At boot lictor asks
the server's /api/tags whether it is up and has the model, and refuses
to start with the fix (ollama pull ...) if not. A bare --ollama uses
the configured model; --model still wins. Whether a given local model
handles Claude Code's tool use well is [UNTESTED] here.
local.ask delegates a narrow job (a first-draft fixture, a file summary,
extraction from text Claude hands it) to a small fine-tuned model served by
Ollama -- by default a model named exsecutor-3b, which you supply; lictor
does not ship or train it. Enable it with [local] enabled = true (also
model, host, timeout_s, max_calls, max_tokens) in config.toml.
It is independent of --ollama: Claude can run on the subscription while
this model runs locally. The subagent has no tools and no memory, sees only
the prompt and the workspace files named in context (paths outside the
workspace are refused), and every result is marked unverified -- Claude
leads and checks it against the spec or the gate. Calls are capped per
session and traced to resource.read("inference:loc-..."). local.status
reports reachability. Exercised against a stand-in HTTP server in the test
suite only; against a real Ollama and a real Exsecutor tune it is
[UNTESTED], and so is the tune's quality.
State lives under XDG-ish directories, lictor appended:
$XDG_STATE_HOME/lictor/ (conversation records, the vault, the overlay
journal, generations, crash reports, artifacts, the private
mutations.git), $XDG_DATA_HOME/lictor/ (saved rlm.* traces),
$XDG_CONFIG_HOME/lictor/ (config.toml, and agents/*.md role files).
$LICTOR_STATE_HOME / $LICTOR_DATA_HOME / $LICTOR_CONFIG_HOME
override each outright, for a throwaway location (lictor's own test suite
uses exactly this to isolate every test onto a tmp_path).
docs/architecture.md is the shape of the process tree -- the inverted
threading model (why SIGINT only ever reaches the main thread, and what
that means for Ctrl-C mid-turn), why there is one in-process MCP server
per namespace, why the tool registry holds the SDK's own SdkMcpTool
objects rather than plain functions, and the boundary that actually
matters: py.* workers cannot touch lictor's own image, self.* is the
only thing that can, and why those two tools being shaped so differently
is deliberate rather than an oversight.
docs/records.md is the append-only conversation record: every JSONL
kind and its fields, the exact fsync ordering a crash can interrupt
(and the bound on what it can lose), where a long tool result spills to
an artifact file, and how a lictor conversation id relates to -- and can
briefly diverge from -- the underlying Claude session id.
docs/mutations.md is the self.* pipeline end to end: the two
redefine target schemes, what symbol_sha256 actually detects and the
exact message a moved tracked definition produces on replay, every check
the clean-process commit probe runs, why a schema change is always
refused, and -- derived by reading every call site in the tree rather
than assumed -- exactly which functions a fn: redefine can and cannot
actually change the behavior of.
docs/evidence.md is the house rule this project holds itself to, and
where it came from: Exsecutor's own CLAUDE.md, applied here with the
same markers ([OPEN], [UNTESTED], [UNREPRODUCED]) and the same
refusal to report a test not watched passing or a number not just
measured. The Evidence section immediately below is the ledger that rule
produces; .trvthnvke.toml is what is meant to keep that ledger from
drifting once the tool is wired in (see that section's own note on its current, unarmed state).
- M0 auth probe passed, 2026-10-01 (
scripts/m0_auth_probe.py, run vianix develop -c python scripts/m0_auth_probe.pyfrom inside a Claude Code session with the script's own scrub ofCLAUDE_CODE_*,CLAUDECODE,CLAUDE_PID,CLAUDE_EFFORT,ANTHROPIC_API_KEY; no API key exists on the machine):claude2.1.266 answeredpong,init: model=claude-opus-5[1m],result subtype: success,is_error: False,num_turns: 1. The reportedtotal_cost_usd: 0.00306is Claude Code's client-side estimate, not a bill. SDK 0.2.163.
- M1 one real turn, 2026-10-01:
python -m lictor --oncestreamed a prose turn and wrotemeta,prompt,assistant_text,resultto the conversation record. Interactive Ctrl-C is [UNTESTED]: there was no tty. - M2 exercised against the real Exsecutor tree, 2026-10-01:
exs.specsliced §13 at lines 2869-3059 ofdocs/spec/exsecutor-spec-v0.4.md, andexs.codesreportedEXS-E0103as "bidi or invisible control character in source" and present incompiler/x86_64/diag/codes.inc. In a live turn the model calledmcp__exs__codesand answered from it. - M4
py.*against real children, 2026-10-01: namespace persisted across evals, aNameErrorreturned as data,while True: passwas killed by process group and the next eval restarted the worker, and the child environment carried noCLAUDE_CODE_*variables. - M4
rlm.inferagainst the real binary, 2026-10-01: one tool-less frame overCLAUDE.mdwith a JSON schema returned{"count": 9, "syscalls": ["read","write","close","fstat","lseek","mmap","munmap","openat","exit_group"]}, the §9.3 allowlist, with the context hashed and one turn charged to the budget. - M4 vault crash survival, 2026-10-01: a real child was
SIGKILLed between marking an item in flight and completing it; a fresh vault still reported the item. - M5 roles reach the model, 2026-10-01: a role file in
<config>/agents/loaded as anAgentDefinitionwith its model, tools and effort, and a live turn delegating to it through the Agent tool returned that role's own answer. Steering a subagent that is already running remains [OPEN]: the SDK offers interrupt and stop, not a message channel. - M5 the README gate is armed and green, 2026-10-01:
trvthnvke verify --failreportsPASS claims=9 checked=9 passed=9 errors=0,nix flake checkpasses bothchecks.testsandchecks.readme, andhooks/pre-commitrefuses a commit it cannot gate rather than passing it. Twelve path-like tokens warn as unbound; the gate'sfail_oniserror. - M6 the worker sandbox, verified through
py.evalitself, 2026-10-01: opening a socket returnedOSError [Errno 101] Network is unreachable, writing outside the workspace returnedOSError [Errno 30] Read-only file system, the interpreter under/nix/storestill ran, and a write inside the workspace succeeded and read back.exs.*is unsandboxed by design. - [UNTESTED] the
claude setup-token→CLAUDE_CODE_OAUTH_TOKENfallback path: not needed, not exercised. - M5 test suite, 2026-10-01:
nix develop -c pytest -q→142 passed(the prior 131, plus 11 new intests/test_roles.py), no regressions. - M5 lint, 2026-10-01:
nix develop -c ruff check lictor tests→All checks passed!. - M5 role loading against the installed SDK, 2026-10-01:
claude_agent_sdk.AgentDefinition's real dataclass fields (checked viadataclasses.fields, SDK 0.2.163) aredescription, prompt, tools, disallowedTools, model, skills, memory, mcpServers, initialPrompt, maxTurns, background, effort, permissionMode. Bothmax_turns(->maxTurns) andeffort-- the two fields the plan singled out as possibly unsupported -- are present, solictor/roles.pydrops neither. A role file written to a throwawayagents/directory and loaded withroles.load(cfg, paths)produced exactly:AgentDefinition(description='Demo role for the M5 verification exercise.', prompt="This is the demo role's prompt body.", tools=['Read', 'Grep', 'Glob'], disallowedTools=None, model='sonnet', skills=None, memory=None, mcpServers=None, initialPrompt=None, maxTurns=6, background=None, effort='low', permissionMode=None). - [OPEN] M5
nix build .#defaultfails, pre-existing, unrelated to M5: the packaged build'scheckPhaseruns the real test suite inside the Nix sandbox, wheregitis not onPATH(it is only added at runtime, viamakeWrapperArgs) --tests/test_overlay.py's two commit/rollback tests spawn a realgitsubprocess and fail withFileNotFoundError: [Errno 2] No such file or directory: 'git'. Confirmed pre-existing, not introduced by M5, by stashing every M5 change and reproducing the identical failure on the unmodified tree. The fix (nativeCheckInputs = [... pkgs.git]inflake.nix) is one line, butflake.nixis outside this milestone's owned files, so it is reported here rather than changed.nix develop -c python -m lictor --version(the dev shell, not the packaged build) works correctly:lictor: 0.1.0/claude-agent-sdk: 0.2.163/claude: 2.1.266 (Claude Code).nix flake checkitself passes (it evaluatespackages.defaultas a derivation but does not build/check it, since there is nochecksoutput yet), and is unaffected by this. - [UNTESTED] the TrvthNvke README gate:
.trvthnvke.tomlis written against the command allowlist actually exercised above, buttrvthnvkeis not a flake input yet, sotrvthnvke extract/lock/verify --failhave not been run even once. Seedocs/evidence.mdfor why the policy is written now regardless, and the note under.trvthnvke.tomlin this repo for the exact steps to arm it.
Anthropic's Agent SDK documentation states: "Unless previously approved, Anthropic does not allow third party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK." lictor is a private tool run by its author on their own account; it offers nothing to third parties and never calls the Anthropic API directly.
MIT. See LICENSE.