OMGCode 0.28.0 is a developer CLI prototype with workspace permission
settings and bounded native file operations through trusted operator commands.
It can send a text conversation to an explicitly selected local LM Studio model
and save that conversation. It can read/list files, exclusively create new
files/directories, and preview a bounded diff against trusted proposed content
in a registered workspace. When a workspace enables model_tools, chat runs
the core's bounded turn/tool runtime so the model can read and list files in
that workspace; with read and write enabled it can request an
approval-gated exact edit of an existing file, and with execute, read, and
write enabled it can request an approval-gated command. Trusted CLI apply can
replace an existing file on Linux ext4 or Windows NTFS. Trusted restore puts a
retained checkpoint's original bytes back through apply, and trusted checkpoint
deletion removes one resolved private entry. The trusted run command starts
one program in a workspace whose execute preference is enabled, under
Landlock and a seccomp socket filter on Linux or a per-workspace AppContainer
on Windows. It uses an operator-declared toolchain profile and records each
run in a run journal. Every run is limited in memory, live processes, and CPU
time. A program started by run can create, change, and
delete workspace files without a checkpoint. The CLI's file commands cannot
delete workspace files, and the CLI cannot use Git or connect to MCP servers.
When a workspace enables model_tools, chat lets the local model read and list
files in that workspace, request an approval-gated exact edit with read/write,
and request an approval-gated command with execute/read/write. Model create,
delete, rename, network, Git, and MCP tools are not implemented. Trusted commands record and apply the Windows container
grants; see command execution.
The core's byte-input replacement inspectors remain read-only. Its file broker
also provides checkpoint_prepare on Linux and Windows with fresh read/write
authority.
Private initialization, exact manifest/payload validation, bounded retention,
and synced journal appends are implemented. No CLI command creates a standalone
checkpoint. The CLI provides existing-only inspection and acknowledgement:
omgcode --data-dir /private/omgcode-data file checkpoints
omgcode --data-dir /private/omgcode-data file acknowledge-checkpoint OPERATION_UUID
These commands require existing workspace settings, but no workspace/session
selection. Inspection never initializes storage and returns metadata only.
Acknowledgement never applies, restores, deletes, retries, or grants access.
A standalone prepared checkpoint remains unresolved until acknowledged.
On Windows the data folder must grant access only to the current user, SYSTEM,
and Administrators, including through inherited grants. Otherwise checkpoint
storage is refused; choose a private --data-dir or remove the extra grant.
See the
checkpoint storage contract.
For a trusted apply, stop all independent writers before starting. Use the preview's current SHA-256 and exact byte count as the precondition. Supply the complete proposed content from a local file:
omgcode --data-dir /private/omgcode-data file apply WORKSPACE_UUID notes.txt --session SESSION_UUID --content-file /private/proposed.txt --expected-sha256 CURRENT_SHA256 --expected-bytes CURRENT_BYTES --writers-stopped
The flag confirms an operating assumption. It does not lock external editors or make the rename conditional on the expected bytes. A reported uncertainty requires inspection of the target and retained checkpoint evidence before acknowledgement or any new apply. See the native apply contract.
To restore a retained checkpoint, read the file's current SHA-256 and byte count first. Those values describe the current file, not the checkpoint. The restore checkpoints the current bytes as a new operation before it publishes:
omgcode --data-dir /private/omgcode-data file restore WORKSPACE_UUID notes.txt --session SESSION_UUID --checkpoint OPERATION_UUID --expected-sha256 CURRENT_SHA256 --expected-bytes CURRENT_BYTES --writers-stopped
A checkpoint restores only the workspace and exact path it recorded. A later
edit causes checkpoint_conflict without mutation. To free checkpoint capacity,
acknowledge any unresolved operation, then permanently delete one entry:
omgcode --data-dir /private/omgcode-data file delete-checkpoint OPERATION_UUID --permanent
Deletion removes the entry's payloads, manifest, and any retained stage. The ledger keeps its history. If deletion is interrupted, every file operation is refused until the same command is repeated. See the restore and deletion contract.
Install Rust through rustup and use a native Windows or Linux development environment. Windows needs the MSVC linker and Windows SDK, normally supplied by Visual Studio Build Tools with Desktop development with C++. Linux needs a working C linker. Run these commands from the repository root:
rustup toolchain install 1.99.1 --profile minimal --component rustfmt --component clippy
cargo build --workspace --locked
cargo run --locked -p omgcode-cli -- capabilities
cargo run --locked -p omgcode-cli -- prompt
The repository pins Rust 1.99.1, edition 2024, for all three crates. This is also the declared minimum version; no older compiler is supported. Cargo.lock fixes the resolved dependency graph. The executable is named omgcode.
The command is omgcode, the model-token variable is OMGCODE_LM_TOKEN,
and new session filenames start with omgcode-. Default private storage uses
the OMGCode application identity; Linux normalizes its directory name to
omgcode. The application does not search for or move previous data.
Version 0.7.0 replaces the OrangeCode namespace. Update scripts and Rust
dependencies to the new command and crate names. Set OMGCODE_LM_TOKEN in
trusted launch configuration if authentication is required. The earlier
ORANGECODE_LM_TOKEN name is no longer read. Existing private data remains in
its original location; the new default does not import earlier settings.
To keep existing workspace settings, select their original private directory
explicitly with --data-dir. Do not relocate the control journal: its recorded
directory path and native identity must still match. Configure a new store
through the trusted workspace commands if the old directory must move.
To reuse a session with a different filename prefix, first close all writers
and keep a private backup. Change only the filename prefix to omgcode-;
retain the timestamp, UUID, .jsonl extension, and all journal bytes. Then use
session inspect with its explicit path and the intended --data-dir before
continuing. The JSONL schemas are unchanged. Inspection does not grant workspace
access or replay actions. For an earlier orangecode- filename, replace only
that prefix with omgcode-. See
ADR-0020.
Use a private application data directory outside your development root. These
examples use Windows paths; on Linux use separate paths such as
/home/me/.local/share/omgcode and /home/me/dev. Create the root and
project directories first. Each command returns JSON. Use the current revision
from its output for the next mutation; replace WORKSPACE_ID and SESSION_UUID
with returned workspace ID and a UUIDv4 session selection.
omgcode --data-dir C:\omgcode-data workspace status
omgcode --data-dir C:\omgcode-data workspace set-root C:\dev --revision 0
omgcode --data-dir C:\omgcode-data workspace register C:\dev\project --revision 1
omgcode --data-dir C:\omgcode-data workspace permissions WORKSPACE_ID --revision 2 --write false
omgcode --data-dir C:\omgcode-data workspace permissions WORKSPACE_ID --revision 3 --model-tools true
omgcode --data-dir C:\omgcode-data workspace check WORKSPACE_ID --session SESSION_UUID --operation read
omgcode --data-dir C:\omgcode-data workspace audit --limit 20
omgcode --data-dir C:\omgcode-data workspace container-grant WORKSPACE_ID C:\dev\project --access read-write --revision 4
omgcode --data-dir C:\omgcode-data workspace container-grant WORKSPACE_ID C:\Users\me\.cargo --access read-execute --revision 5
omgcode --data-dir C:\omgcode-data workspace container-revoke GRANT_UUID
status initializes an absent store at revision zero. check and audit
require existing state. Flags take explicit true or false values. Read/write
default to enabled; execute, task-network, host-services, and model-tools
default to disabled. All decisions still report execution_allowed: false;
only the trusted run command starts a process, and the model command tool
reaches it only after consuming an approval. Settings commands do not dispatch
tools. --model-tools true lets chat offer the model read/list tools, with
read/write the approval-gated edit tool, and with execute/read/write the
approval-gated command tool; see
model tools.
See the workspace contract for limits and failures.
container-grant and container-revoke work on Windows only. They change ACLs
for the workspace's AppContainer and record each change; see
container grants.
Version 0.27.0 stores provider API keys in protected OS storage and binds each
one to an api_key provider profile (ADR-0042).
No provider adapter reads a stored credential yet; chat still uses only the
prototype OMGCODE_LM_TOKEN input. Subscription and none profiles refuse a
credential.
In PowerShell:
omgcode --data-dir C:\omgcode-data workspace provider-profile-add work --kind openai --auth api_key --revision 6
$key = Read-Host -AsSecureString -Prompt 'API key'
[System.Net.NetworkCredential]::new('', $key).Password | omgcode --data-dir C:\omgcode-data workspace provider-credential-set work --revision 7
Remove-Variable key
omgcode --data-dir C:\omgcode-data workspace provider-profile-show work
omgcode --data-dir C:\omgcode-data workspace provider-credential-remove work --revision 8provider-credential-set reads the secret from standard input only. It never
accepts the secret as an argument or environment variable, and it refuses a
terminal, which would echo the secret as it is typed. It reads at most 16 KiB
plus one line ending, removes exactly one trailing \n or \r\n, and refuses
empty input. Pipe the secret without placing it on a command line, as above.
The secret is read before the control store is opened, so no settings lock
is held while the command waits for input.
Windows PowerShell 5.1 sends piped text in its $OutputEncoding, which is
ASCII by default, and appends CRLF; the CLI removes the CRLF. A non-ASCII key
needs PowerShell 7 or an explicit UTF-8 $OutputEncoding. The plaintext is
briefly held as a .NET string in the shell.
In bash, read -s does not echo, and printf is a builtin, so the key is not
in a process argument list or the shell history:
IFS= read -rs key && printf '%s' "$key" | omgcode --data-dir ~/omgcode-data workspace provider-credential-set work --revision 7; unset keyEach set stores a new credential under a fresh random identifier, then records
provider_credential_bound with the profile, the identifier, and the backend.
Setting a credential on a bound profile rotates it: the old native item is
deleted only after the new binding is recorded. provider-credential-remove
records provider_credential_removed, then deletes the native item.
provider-profile-remove names a bound credential in its own
provider_profile_removed event and then deletes the item. Output and
workspace status report the identifier and backend, never the secret. When
an unbound item cannot be deleted, the command still succeeds and reports a
warning with code credential_orphaned and the identifier to remove by hand.
Credential failures use stable error codes: credential_unavailable,
credential_locked, credential_not_found, credential_exists,
credential_corrupt, credential_input, credential_io,
credential_prompt_required (the Secret Service asked for confirmation,
which OMGCode never shows), credential_orphaned (nothing was recorded, and
an item for the named identifier may remain and could not be deleted), and
credential_binding_uncertain. The last means the binding's journal write
failed after it began, so it may or may not be recorded. The new item is
kept and the message names it, and any replaced identifier. Run
provider-profile-show: if it shows the new identifier, keep it or remove it
with provider-credential-remove, and delete the replaced item by hand;
otherwise delete the new, unbound item by hand. A recorded binding never
names an item that OMGCode deleted. capabilities reports credential_store with the
backend and its state. A control journal written by 0.27.0 cannot be read by
0.26.0.
- Windows: each credential is a DPAPI blob for the current user in
<data-dir>\credentials-v1, written create-only with an owner-only DACL. The data folder must meet the private-root rule used by checkpoint storage; otherwise the store iscredential_unavailable. An edited, truncated, or copied blob, or a broadened DACL, iscredential_corrupt. - Linux: each credential is one item in the Secret Service default
collection on the session bus, for example the gnome-keyring login
collection. OMGCode never unlocks a collection: unlock it outside OMGCode,
or the command fails with
credential_lockedbefore anything is recorded. It never runs a Secret Service prompt either: a service that asks to confirm a new item or a deletion gets the prompt dismissed, and the command fails withcredential_prompt_required. An item is first created as an empty placeholder with anomgcode_state=pendingattribute; the secret is then sent through the encrypted session and the marker removed. A placeholder left by an interrupted store loads ascredential_corrupt. No bus, service, or default collection iscredential_unavailable. Nothing falls back to a plaintext file.
Any process running as the same user can read these credentials. The stores protect them at rest and from other users, not from same-user code.
Enable execute, declare a toolchain profile, and run a program. On Windows,
grant the workspace read-write first, and grant read-execute on any toolchain
root that application packages cannot already read. These examples continue
the revisions above.
omgcode --data-dir C:\omgcode-data workspace permissions WORKSPACE_ID --revision 6 --execute true
omgcode --data-dir C:\omgcode-data workspace container-grant WORKSPACE_ID C:\Users\me\.rustup\toolchains\1.99.1-x86_64-pc-windows-msvc --access read-execute --revision 7
omgcode --data-dir C:\omgcode-data workspace profile-add rust --root C:\Users\me\.rustup\toolchains\1.99.1-x86_64-pc-windows-msvc --path C:\Users\me\.rustup\toolchains\1.99.1-x86_64-pc-windows-msvc\bin --root C:\Windows\System32 --path C:\Windows\System32 --revision 8
omgcode --data-dir C:\omgcode-data run WORKSPACE_ID --profile rust -- cargo build --offline
omgcode --data-dir C:\omgcode-data runs audit --limit 20
omgcode --data-dir C:\omgcode-data runs acknowledge RUN_UUID
omgcode --data-dir C:\omgcode-data runs archive --archive-dir C:\omgcode-archive
A Windows profile that links with MSVC also needs the MSVC tools and Windows
Kits directories as roots, the MSVC bin\Hostx64\x64 directory on PATH, and
the INCLUDE, LIB, and VCINSTALLDIR values a developer prompt would set.
On Linux a typical profile is --root /usr --path /usr/bin plus the
toolchain's own root. The run receives only the profile's PATH and
variables, plus runner-owned home and temporary locations. Output is printed,
never stored. --host-services also needs --host-services true on the
workspace and works only on Linux. --max-memory-mib, --max-processes,
--max-cpu-secs, and --max-disk-mib set the
tree limits; the defaults are 8192 MiB, 1024, 7200
seconds, and 8192 MiB of net disk growth. The disk limit is sampled, not a
filesystem quota. The execution guide
owns the checks, the journal, and the known limits, including those for Node
on Windows.
On Linux, start run in a delegated cgroup of its own, or it is refused:
systemd-run --user --scope -p Delegate=yes -- omgcode --data-dir ~/omgcode-data run <workspace-id> --profile system -- cargo test
The scope must hold only that command, so do not start a shell inside it and run several commands there.
When a root is configured, new sessions use stable IDs from the persisted workspace registration. Invalid settings or outside-root selections fail. Existing text-only journals remain readable without inferred access grants. With no configured root, the earlier text-only behavior remains available and sets no implicit root. Registrations store settings and audit history; they do not create project folders or grant access. A broader project registry and the folder/session tree remain future work.
Scoped file commands (read, list, create, mkdir, diff, apply, and
restore) require
existing workspace settings, a configured development root, a registered
workspace ID, and an explicit session UUID. They do not initialize settings,
infer a root, or treat a journal's workspace metadata as a grant. read, list,
and diff require the read preference. create and mkdir require the write
preference. apply and restore require both preferences and a supported
native mount. Execute remains disabled. The audit, acknowledge,
checkpoints, acknowledge-checkpoint, and delete-checkpoint commands require
existing workspace settings.
They do not require a configured root, workspace registration, or session
selection. Chat advertises the read/list tools when the session's workspace
enables model_tools, the edit tool when read and write are also enabled,
and the command tool when execute, read, and write are also enabled; see
model tools.
Capability JSON separates implementation from availability. On Linux and
Windows, workspace_file_broker_implemented is true, while
workspace_file_broker and exclusive_file_creation are null (unknown). On
other platforms, all three values are false. The CLI does not probe the ambient
filesystem for capability reporting. A command checks settings, scope, policy,
and native requirements when it runs. These values do not promise that an
operation can proceed. edit_previews is true on Linux and Windows for the
trusted CLI preview. existing_file_replacement is true on Linux and Windows to indicate
implementation, and false elsewhere. The CLI does not probe the mount, metadata,
or permissions for that flag. checkpoint_restore and checkpoint_deletion
follow the same rule for file restore and file delete-checkpoint.
model_read_list_tools is true on Linux and Windows, and tool_policy is
read_list_when_workspace_model_tools_enabled_edit_and_command_require_approval
there. model_write_tools and model_command_tool are approval_required.
None of them reports whether any workspace enables the preference.
workspace_file_tools, which covers general model file tools such as create,
delete, or rename, remains false.
omgcode --data-dir C:\omgcode-data file read WORKSPACE_ID --session SESSION_UUID src\main.rs --max-bytes 65536
omgcode --data-dir C:\omgcode-data file list WORKSPACE_ID --session SESSION_UUID src --limit 100
omgcode --data-dir C:\omgcode-data file create WORKSPACE_ID --session SESSION_UUID notes.txt --content "Review this file"
omgcode --data-dir C:\omgcode-data file mkdir WORKSPACE_ID --session SESSION_UUID notes
omgcode --data-dir C:\omgcode-data file diff WORKSPACE_ID --session SESSION_UUID src\main.rs --content-file C:\drafts\main.rs
omgcode --data-dir C:\omgcode-data file audit --limit 20
omgcode --data-dir C:\omgcode-data file acknowledge OPERATION_UUID
omgcode --data-dir C:\omgcode-data file rotate --archive-dir C:\private-audit-exports
omgcode --data-dir C:\omgcode-data file audit --archive ARCHIVE_PATH --limit 20
Omit the list path to list the selected workspace root. The empty path is not
valid for read, create, mkdir, or diff. Reads return bounded bytes as untrusted
data. Creation refuses every existing entry. file diff reads the current file
through the broker, reads the complete proposed content from the trusted
operator-selected local file, and returns a bounded single-hunk diff with exact
digests and sizes. The proposed source is opened read-only without following a
final link; Windows reparse, device, and non-regular handles are rejected. It
accepts only UTF-8 content, limits each side to 1 MiB and, when a diff is
needed, 65,536 lines, and limits the rendered diff to 64 KiB. It never writes to the workspace, creates no
checkpoint, and is not a replacement operation. The preview is a snapshot of the
bytes read; a later replacement must recheck the content identity. File-operation intents and outcomes use
a separate private file-operations-v1.jsonl; the control-v1 settings journal
and session journal schema remain unchanged. The file journal stores operation
metadata, not file contents. If a create result is uncertain, inspect the path
and audit record, then acknowledge the operation. Acknowledgement records
inspection only. It does not retry, repair, or delete the entry. See the
workspace file-access contract for bounds and native failures.
The archive directory must already exist, be private, be on the same filesystem,
and be outside both the development root and application-data directory.
file rotate and archived audit inspection need existing settings, but no
workspace/session selection. Rotation refuses unresolved operations and returns
a lossless path, SHA-256, and event count. It preserves the original bytes and
does not delete or replay archives. The next file operation starts a fresh log.
A file_rotation_uncertain error requires inspection of the active path and the
reported candidate before retry. Export retention is managed by the operator.
See archive and recovery details.
omgcode_core::turn provides a session-owned runtime for one bounded
model/tool turn. chat runs it when the session's workspace enables
model_tools. A caller supplies a model implementation, an open schema-version-2 session, the
trusted application-data directory, and the workspace ID. The runtime:
- parses strict OpenAI-style function calls for
workspace_read_file,workspace_list_directory,workspace_edit_file, andworkspace_run_command; - rejects unknown tools, malformed or duplicate arguments, absolute or parent paths, and duplicate call identifiers before dispatch;
- opens the control store for each broker call, obtains a fresh session binding, and releases the settings lock before the next model request;
- reserves assembled-prompt capacity and enforces the selected per-message limit before recording any tool intent, result, or message;
- enforces hard maxima of four rounds, eight calls per round, sixteen calls per turn, 16 KiB per source-labelled tool message, and 256 KiB aggregate tool text, with a 30-second cooperative deadline by default (chat uses 120 seconds);
- records
tool.requested,tool.completed, and schema-version-2 tool messages, and records the exact tool schema version and names in the request manifest; - treats every tool result as source-labelled untrusted user-level content and never promotes it to the system role;
- denies every call with
model_tools_disabledunless the workspace's livemodel_toolspreference is still enabled; - sends saved tool results from earlier turns again only while the live
model_toolsandreadpreferences both allow it, and otherwise replaces each with a fixed withheld notice; - offers
workspace_edit_fileonly under livemodel_tools,read, andwrite, andworkspace_run_commandonly whenexecuteis also enabled; every edit or command first needs a trusted single-use approval; - reports the final reply's provider
finish_reason.
The runtime has no create, delete, rename, Git, MCP, or network tool. Its only
write is the approved exact edit through checkpointed apply, and its only
process execution is the approved command through the trusted runner.
LocalToolModel adapts the LM Studio client to its model interface. The adapter
sends the tool definitions in the OpenAI-compatible tools field, parses the
response with the strict duplicate-key-rejecting parser, and returns each call
unvalidated for the runtime to check. Other provider adapters must do the same
and keep the subscription/API profile split. See the
session contract for the event sequence and the
file-access contract for broker checks.
Start LM Studio separately and load the model you intend to use. Check the loaded model's context capacity in LM Studio. A model's advertised maximum can differ from its loaded capacity. The following example uses the user's loaded google/gemma-4-e4b profile with a verified capacity of 131,072 tokens:
cargo run --locked -p omgcode-cli -- chat --workspace . --model google/gemma-4-e4b --context-tokens 131072 --max-output-tokens 512 "Reply with READY."
The default endpoint is http://127.0.0.1:1234/v1. Override it with --endpoint only for an explicitly selected local service. This prototype accepts HTTP, literal loopback IP addresses, an explicit nonzero port, and the /v1 path. Hostnames, remote addresses, redirects, and proxy discovery are disabled. A loopback connection does not establish how the selected server handles data upstream. Verify the server's own configuration before sending sensitive text.
The CLI sends the compiled base prompt, optional --instructions user-level
preferences, the saved user/assistant history, and the current message. When the
session's workspace does not enable model_tools, it sends no tool
definitions and rejects structured tool calls. Saved tool results from earlier
turns are not sent: each is replaced by a fixed withheld notice, and the journal
keeps the original. The output reports model_tools.mode as disabled with a
reason and a withheld_tool_results count. Text which resembles a command
remains text.
When the workspace enables model_tools, chat offers workspace_read_file and
workspace_list_directory. When read and write also allow it, it offers
the approval-gated workspace_edit_file. When execute, read, and write
also allow it, it offers the approval-gated workspace_run_command. The model may make up to
four requests in one turn. Each read/list call is rechecked against live
settings and stays inside the workspace. Results return to the model as
source-labelled user messages. The configured LM Studio token is removed from
each result before it is recorded or sent. A tool call that contains the token
is refused with a provider error before it is recorded, because editing its
arguments could change the requested path. Add
--auto-compact --compact-threshold <tokens> to compact older active context
before a turn. session compact <journal> --endpoint <url> --model <name> --context-tokens <n> --summary-tokens <n> performs the same manual action.
Compaction records a schema-v3 context.compacted event, keeps the original
messages, and injects a labelled untrusted summary; it never grants authority.
Chat reports a conservative context meter. Saved tool results are sent again,
to a turn or to the summarizer, only while the live model_tools and read
preferences both allow it; a summary built from them follows the same rule. Chat
prompts for no approval: a command or edit call first records a pending
approval and returns approval_required; the operator decides it between
turns, and a later identical call consumes it. A command then calls the trusted
runner; an edit calls the checkpointed apply, as the
model edit workflow shows.
The output reports model_tools.mode as enabled, with the workspace ID,
rounds, call count, tool bytes, and withheld count. reply.finish_reason is length when the token
limit cut the final reply short; the turn is still recorded as complete. A refused or invalid call ends the turn with a permission,
tool_call, or tool_limit error, recorded in the journal.
omgcode --data-dir C:\omgcode-data chat --journal <journal-path> --model google/gemma-4-e4b --context-tokens 131072 "Summarise README.md."
Output is JSON so untrusted control characters are escaped rather than written as terminal instructions.
Each text-only invocation sends one non-streaming request; a tool-enabled turn
sends at most four. When --auto-compact compacts before the turn, the
summarizer requests come first: at most 16 per round, with at most four
combination rounds after the first. session compact sends only summarizer
requests under the same bound. There is a five-second connect timeout and a thirty-second
timeout per request, with no automatic retry or provider fallback. A
tool-enabled turn also stops at a 120-second cooperative deadline. A slow first inference can time out. Its remote outcome can
be unknown, and a retry is a new explicit user action.
Optional server authentication can be supplied to the trusted CLI process with OMGCODE_LM_TOKEN. The CLI retains the token in memory only and sends it as a sensitive Authorization header. It does not save it or pass it to a child task. Environment-based input is a temporary prototype interface, not protected credential storage or a claim of memory erasure. Protected storage for API keys exists (see provider credentials), but no adapter reads it yet; adapter use and the account/settings interface remain required. Use the no-token profile only for an explicitly selected service configured for it.
workspace_edit_file takes a workspace-relative path, a non-empty
old_text that must occur exactly once, and a new_text, all within the 4 KiB
argument limit. It edits only an existing UTF-8 regular file of at most 1 MiB,
before and after the edit. A missing, repeated, or unchanged old_text
returns the recoverable edit_no_match, edit_ambiguous, or edit_unchanged
result. Each call reads the live file through the audited broker. Its approval
digest covers the session, workspace, normalized path, and the size and SHA-256
of the current and proposed bytes, so a file that changed after the request
needs a new approval (ADR-0043).
omgcode --data-dir C:\omgcode-data chat --journal <journal-path> --model google/gemma-4-e4b --context-tokens 131072 "Rename the helper in src\lib.rs."
omgcode --data-dir C:\omgcode-data session inspect <journal-path>
omgcode --data-dir C:\omgcode-data approvals list
omgcode --data-dir C:\omgcode-data approvals approve APPROVAL_UUID --writers-stopped
omgcode --data-dir C:\omgcode-data chat --journal <journal-path> --model google/gemma-4-e4b --context-tokens 131072 "The edit is approved; retry it."
- The first chat turn returns the tool result
approval_requiredwith an approval ID. Nothing is written. session inspectlists the recordedtool_requests. Review the exactold_textandnew_textin theworkspace_edit_filerequest's arguments. The approval summary shows only the path, sizes, and short digests, never file text.- Stop every other writer to the file, then approve with
--writers-stopped. Without the flag, approval of afile_writerequest is refused; the flag is refused for other operations. Useapprovals deny <id>to refuse the edit. - In a later turn, the model repeats the identical call. It consumes the approval and applies the edit through a checkpoint. The result reports the path, new size, SHA-256, and checkpoint operation ID, never file contents.
The approval is consumed before the apply, so a failed apply spends it. A
conflict, pending or busy checkpoint store, or unsupported filesystem returns a
recoverable result with its checkpoint code. The apply cannot detect a
concurrent writer; the acknowledgement records the operating assumption only.
Restore and checkpoint management stay trusted file commands.
By default, journals use the platform's per-user local application data directory. A trusted operator can override this with --data-dir. Keep that directory outside project folders, under an account-protected location. Do not paste credentials into messages or preferences: these inputs are saved as text.
omgcode session new --workspace . --title "Prototype test"
omgcode session inspect <journal-path>
omgcode chat --journal <journal-path> --model google/gemma-4-e4b --context-tokens 131072 "Continue the conversation."
omgcode session archive <journal-path>
omgcode session restore <journal-path>
Use the full journal path returned in the JSON output. The commands above use an installed executable; during development, prefix each with cargo run --locked -p omgcode-cli -- instead of omgcode. --instructions applies to the current invocation and is recorded in its manifest. Resume does not silently reuse earlier custom instructions or model settings. Supply them again when needed. The current compiled base always replaces historical base snapshots.
Results also include a lossless journal_native object. The journal string is null when the path cannot be represented as Unicode; journal_display is always display text. Supply the serialized native object with --journal-native instead of a positional path for session commands, or instead of --journal for chat. Only the originating OS's encoding is accepted. Post-open chat failures include the same locator under error.session, so a failed first request can be inspected without searching for its journal or creating another session.
Archive and restore keep the same filename and session ID. They start no work. Archiving an active turn fails. If the CLI stopped during a turn, inspect the journal, then explicitly mark that turn failed before resuming or archiving:
omgcode session interrupt <journal-path>
Interrupt acquires the exclusive journal lock. It cannot interrupt another running writer. It records operator_interrupted for an abandoned turn, without retrying a request or claiming remote rollback. Invalid or truncated journals are rejected without modification. Automated repair and a recovery UI remain planned. See the complete session contract.
| Resource | Prototype limit |
|---|---|
| Custom instructions | 16 KiB of UTF-8 text |
| Each user/assistant message | 16 KiB of UTF-8 text |
| History in one request | 128 messages |
| Assembled text / encoded request | 256 KiB each, checked separately |
| Encoded provider response | 1 MiB |
| Encoded journal event, including LF | 64 KiB |
| Journal | 8 MiB and 10,000 events |
| Tool call arguments in a session event | 4 KiB |
| Model edit file size, before and after | 1 MiB |
| Read file size per call | 15 KiB maximum, 8 KiB default |
| Edit preview content | 1 MiB per side |
| Edit preview lines | 65,536 per side when changed |
| Edit preview diff | 64 KiB |
| Source-labelled tool message | 16 KiB |
| Tool rounds per turn | 4 |
| Tool calls per round / per turn | 8 / 16 |
| Aggregate tool text per turn | 256 KiB |
| Cooperative turn deadline | 30 seconds by default; 120 seconds for chat |
| Raw tool calls accepted from one response | 64 before runtime validation |
These are ordinary quotas. Active turns reserve one terminal event and 1 KiB for it. CLI requests preflight their encoded manifest and user event, and reserve space for a maximum-size assistant event before recording the turn marker. A deterministic reply-size failure closes the turn; an uncertain write/sync failure stops the writer instead. For older journals already full with an active turn, one terminal recovery event of at most 1 KiB may exceed the ordinary quotas. Readers accept only that bounded exception. Full journals remain inspectable; further ordinary events require a new session. No history is removed to make room.
The context guard estimates input from UTF-8 bytes plus fixed message overhead, then reserves the configured output tokens and headroom. This is a conservative heuristic, not a tokenizer or a guarantee for every chat template. The operator must supply a validated loaded-model capacity. Compaction and automatic history selection are not implemented: requests over a limit fail before inference. Provider-reported usage and finish reason appear in the reply JSON. Durable usage events, streaming chunks, and large-output artifacts remain planned.
| Crate | Responsibility |
|---|---|
| omgcode-core | Compiled prompt, bounded model adapter, session/control/file-operation/run journals, workspace policy and toolchain profiles, broker orchestration, trusted runs, bounded turn/tool lifecycle, and non-destructive edit previews |
| omgcode-cli | Trusted operator input, one-turn chat orchestration with optional read/list and approval-gated command model tools, bounded file and preview commands, trusted run, JSON output |
| omgcode-platform | Native journal validation, directory identity, handle-relative workspace file operations, Windows AppContainer grants, interrupt-to-cancel handling, and a process-tree runner with Linux Landlock/seccomp and Windows AppContainer confinement |
Core and CLI forbid unsafe code. The platform crate denies unsafe code except
inside its reviewed Windows handle wrappers for directory identity, native file
operations, process creation and job control, AppContainer profiles and ACL
grants, and console control handler registration, and its Linux pre-exec
prctl, seccomp, and close_range calls and sigaction registration. Linux uses Rustix's safe openat2 API. Directory registration
uses native file IDs and requires directory creation-time metadata. The broker
reopens the registered root and workspace, checks their identities and creation
times, then accesses relative names through retained handles. These live checks
apply to broker calls; directory identity recording alone remains configuration
metadata.
Rust's stable metadata API does not
provide the needed Windows hard-link count. The wrapper borrows the existing
handle and checks GetFileInformationByHandle; it never takes ownership of a raw
handle. Linux broker traversal requires kernel 5.6 or later for openat2 and
available /proc/self/fd support. Required beneath-root, no-symlink,
no-magic-link, and no-mount-crossing resolution has no weaker fallback.
Unsupported APIs fail closed. Windows uses native handle-relative and
reparse-point controls. Existing
parent directories must remain trusted. Windows ACL hardening, local filesystem
qualification, and power-loss durability are still required. The broker is not
whole-user or process containment.
Session workspace IDs in session journals are descriptive metadata. They grant
no access. Each scoped file operation supplies the workspace ID and session
UUID to the loaded control store; the broker checks the current binding, policy
revision, registration, and native directory identity. Audit and acknowledgement
commands use existing settings to inspect or resolve file-operation recovery;
they do not use a workspace or session binding. The control journal persists
workspace registrations, settings, revisions, and policy audit events. File
operations use a separate journal, so they do not change the control-v1.jsonl
or session JSONL schemas. A broader project registry and the folder/session tree remain
future work. The CLI's explicit journal path is a trusted operator interface;
it must not become a raw-path command in the future web interface.
Direct dependencies have specific purposes:
| Dependency | Purpose and selected surface |
|---|---|
| serde / serde_json | Typed JSON serialization and bounded protocol parsing; derive macros run during compilation |
| uuid | Random UUIDv4 identifiers and typed JSON identifiers; OS-backed randomness through its dependency graph |
| libc (Unix only) | Locked at 0.2.191; supplies O_DIRECTORY and O_NOFOLLOW constants to safe std::fs::OpenOptions flag configuration, avoiding ABI-specific numeric flags without adding unsafe core code |
| rustix (Linux only) | Locked at 1.1.6 with the fs feature; supplies safe Rust wrappers for openat2, directory-relative opens, metadata, enumeration, and sync without adding unsafe Linux code |
| time | UTC date layout and RFC 3339 formatting/parsing |
| sha2 | Standard SHA-256 prompt digest; no custom cryptography |
| thiserror | Typed component errors; derive macro runs during compilation |
| reqwest | Blocking HTTP client; default features disabled, no TLS backend or hosted execution used in this loopback-only increment |
| clap | CLI parsing and help; derive macro runs during compilation |
| directories | Platform application-data location selection |
| windows-sys | Maintained Windows API bindings behind narrow reviewed wrappers for Win32/WDK Foundation and Storage/FileSystem, Security, DPAPI (Win32_Security_Cryptography), I/O handles, processes and jobs, and console control events |
| zeroize | Zeroes owned secret buffers on drop; alloc only, no derive macro |
| secret-service (Linux only) | Freedesktop Secret Service client over pure-Rust zbus, with the tokio runtime and Rust AES/DH session crypto (rt-tokio-crypto-rust); its blocking API runs an internal tokio runtime |
| tempfile | Private disposable test data; development dependency only |
The selected direct crates declare MIT and/or Apache-2.0 licensing and support the build targets. Cargo.lock and each update's metadata need review; this is not a full audit of transitive dependencies, unsafe code, build scripts, or procedural macros. No Git dependencies or downloaded execution backends are used. Use maintained libraries for HTTP, cryptography, and OS bindings instead of custom implementations. Build dependencies execute with the developer's build permissions, not with future OMGCode task restrictions.
Run the Cargo verification baseline
on both Windows and Linux. The Rust workflow runs formatting, strict Clippy,
unit/integration tests, and separate documentation tests. On Linux the run and
tree-limit tests start themselves in systemd-run --user scopes, so they need
a running user service manager; without one they fail. The Linux credential
tests need an unlocked Secret Service default collection on the session bus
and fail without one. With gnome-keyring, one empty password line creates and
unlocks a login collection:
printf '\n' | gnome-keyring-daemon --unlock --components=secrets. Use a
scratch XDG_DATA_HOME to keep test keyrings apart from your own. Tests use
private data and loopback fixtures. They do not call a live model. Live compatibility checks
are explicit, bounded checks of a particular server/model/auth profile.
The toolchain acceptance tests are ignored by default. After a change to runs,
profiles, or confinement, run them on both platforms with the toolchain
variables listed in crates/omgcode-cli/tests/toolchain_acceptance.rs:
cargo test -p omgcode-cli --test toolchain_acceptance --locked -- --ignored
Do not infer whole-user/process containment, Git safety, same-user credential
isolation, release filesystem support, or full coding-agent support from these tests. The
broker supports bounded file operations through trusted CLI input and the core
turn runtime, which chat drives for read/list and an approval-gated command when
a workspace enables model_tools. Live provider tool-call compatibility and
process containment
remain separate boundaries.