Qriton CLI

A coding agent for your terminal and paired iPhone, running on infrastructure you control. Use a local model on your own machine, or any major model API, in the same session: your conversation, approvals and project memory stay with the work when you switch models.

Use Qriton HLM to work with Qriton's published models in the same project: set up a Python runtime, download verified weights, edit runner code, and inspect saved results.

npm install -g qriton

What's new in 0.5.0

• Guided HLM setup. Preview and install a Python runtime and starter project for supported HLM5 models.
• Editable model projects. Work on runner code, execute registered commands, and review saved outputs from the CLI or coding assistant.
• HLM facts in coding tasks. Discover saved facts and verify their current answers with local model inference.
• Clearer recovery. File tools provide guidance for recoverable path mistakes, and transient Ollama failures use the configured retry policy.

Get started

Qriton runs on macOS, Linux and Windows. On Windows, install PowerShell 7 for the best results; without it, commands run in cmd.exe. You need Node 22.16 or later (22.x) or Node 24, and Ollama running for local models.

qriton pull qwen3.5:4b     # download the default local model
cd ~/code/your-project
qriton

Ask for a change in plain language. Qriton reads your code, proposes the edit and waits for you:

Approval · File change
  - # qriton
  + # Qriton

  [y approve] · n reject · a always
  a allows all file edits this session without asking again

y applies it, n leaves the file alone. Nothing is written before you answer. Run qriton from the project folder, or point it there from anywhere with qriton -C ~/code/your-project. If something doesn't start, run qriton doctor.

On a smaller machine, qriton --light runs a lighter session: a smaller context, no thinking, keyword-only memory.

Qriton HLM

Create a workspace for a supported HLM5 model. Guided setup requires Python 3.10–3.12; model weights are downloaded separately from Hugging Face.

mkdir my-hlm-project
cd my-hlm-project
qriton hlm setup                         # list supported models
qriton hlm setup hlm5-1b                 # preview runtime and project setup

Review the plan, then copy its printed apply command, including the fingerprint:

qriton hlm setup hlm5-1b apply <fingerprint>

Download the model and run it:

qriton hlm fetch hlm5-1b
qriton hlm doctor
qriton hlm run hlm5-1b -- --prompt "Once upon a time" --tokens 16
qriton hlm runs

Setup creates an environment and editable Python code inside your workspace. Open Qriton there and ask it to inspect or change .qriton/hlm/project/model/run.py, run the model, and review its output. Start a new coding session after setup to load the updated settings. The guided runtime uses CPU inference. See the setup guide for interpreter selection, disk requirements, and supported platforms.

| Model | Download size | Workbench support | |---|---:|---| | hlm5-1b | 4.2 GB | Completion and memory edits | | hlm5-1b-hybrid | 4.2 GB | Completion and memory edits | | hlm5-3b | 10.8 GB | Completion |

Existing projects. Select a compatible registry with hlm.projectRegistry in user configuration, then run Qriton in that model workspace:

qriton hlm projects                      # browse registered projects
qriton hlm project <id>                  # inspect a runner and required files
qriton hlm run <id>                      # execute its registered command
qriton hlm runs                          # review saved outcomes

The coding assistant can inspect and edit these projects and request approval to run their commands. Other architectures and custom checkpoints need their own loaders and registered runners. See existing model projects.

Editable memory. The 1B models support checked, reversible single-token answers at exact prompts, with up to 32 fact addresses per overlay. Base weights stay frozen. Preview checks the proposed answer, retained facts, and control prompts before an edit can be applied. These checks do not establish general learning or accuracy on paraphrased questions. Forgetting deactivates an edit and retains its history.

memorize "The capital of Veldoria is" " Paris"

Save that line as edit.hlm, provide a control suite, then use:

qriton hlm preview hlm5-1b edit.hlm controls.json
qriton hlm apply <proposal-id>
qriton hlm facts hlm5-1b
qriton hlm read hlm5-1b <fact-id> <revision>
qriton hlm restore <proposal-id>

See the HLM guide for control examples, corrections, restoration, and using facts in conversation. HLM supplies a separate model workbench; your selected coding provider still handles the conversation and code changes. Saved fact routing and fresh native model reads are separate operations.

These commands also work after /hlm in terminal or paired-phone chat. On a qriton serve host, the models and Python runtime stay on the host; the phone provides the conversation and approvals. See the phone workflow. Published models are available on Hugging Face.

What stays on your machine

Running Ollama on this computer keeps chat inference local. A remote Ollama server or hosted model receives the conversation and selected code context; search, embedding, mesh and mobile services also have their own destinations. Choosing a local chat model alone does not disable those services. API keys are stored in the macOS Keychain, libsecret on Linux, or a private file, never in your project or configuration.

For a paired phone with a configured gateway, pushes contain generic status such as "Approval waiting" by default, plus session/approval identifiers. Setting "mobile": { "preview": true } in user configuration opts into content previews, which travel through the gateway and Apple's push service (APNs). Push requests obey Qriton's HTTP network policy. They are separate from the encrypted mesh messages.

Qriton's file tools only work inside the project folder you started it in. Commands run only as your approval mode allows, and a command you approve runs with your own permissions, so read it before you say yes. Simple reads inside the project run without asking.

Choose a model

A plain name means a local Ollama model; a prefix selects a provider:

qriton --model qwen2.5-coder:7b          # local, through Ollama

qriton auth anthropic                    # save a key once
qriton --model anthropic/claude-opus-5

qriton auth openai
qriton --model openai/gpt-5-mini

qriton auth xai
qriton --model grok-4.6

Any OpenAI-compatible server works too (OpenRouter, Groq, vLLM, LM Studio):

export OPENAI_BASE_URL=https://openrouter.ai/api/v1

Switch at any time with /model <name>, or browse with /models; the conversation carries over. A practical pattern is to explore with a local model, switch to a hosted one for a hard change, and switch back.

Ollama on another computer. /servers finds Ollama servers on your local network, and /server <url> selects one. Qriton checks it and remembers it.

If a model stops responding. Qriton retries a dropped connection, timeout or overloaded service by itself. You can also list backup models; Qriton then asks before switching, or switches on its own and tells you (see Configuration).

Everyday use

qriton                                   # interactive session
qriton "why does the build fail"         # start with a question
qriton -p "list the exported types"      # answer once, print, exit
qriton -p --mode auto-edit "fix the typo in README"
qriton --plan "how would I add login"    # investigate without changing anything
qriton --continue                        # resume the last session here
qriton --image screenshot.png "what is wrong here"

While Qriton works you can type an addition or correction and press Enter; it joins the task at the next safe step. Esc interrupts. Ctrl+C twice or /exit quits.

Code from your iPhone

After configuring the mesh and pairing the Qriton iPhone app with qriton mesh pair, leave a host running in the project you want to work on:

qriton -C ~/code/your-project serve

Open that host in the app, send a coding task and review its proposed changes and command approvals. The work runs on the host with its configured coding model and workspace tools. Use /project to see current changes and previous work, then choose a conversation to resume. Use Stop to interrupt an active task or workbench command.

Type /hlm to inspect and use the host's Qriton models alongside that coding workflow. Model files, input files and Python runtimes live on the host; the phone supplies the conversation, choices and approvals. These slash commands are available on a qriton serve host; a terminal session shared with /share has a different command interface.

Pick up unfinished work

Run this in your project when you return to it:

qriton project             # current Git changes, recent tasks and last recorded checks
qriton resume <session-id> # use an id from the overview to continue that conversation
qriton project json        # the same overview as structured data

The overview runs offline without loading a model or requesting credentials. It reads sessions for this workspace and reports missing Git or session history directly. Older conversations without a saved outcome show that the outcome is unknown. Recorded checks describe that earlier turn; they do not certify the files currently on disk.

Inside a session, use /project, then /resume <session-id>. The same commands work from a paired phone connected to a serving host; its overview offers resume choices. Resuming opens the conversation so you can continue the work under your current approvals.

Approval modes

| Mode | File changes | Commands | |---|---|---| | suggest (default) | ask | ask | | auto-edit | apply | ask | | full-auto (--yolo) | apply | run | | plan (--plan) | blocked | blocked |

Change mode with /mode, or cycle with Shift+Tab when the input is empty. /auto on runs everything without prompts for the current session, and /auto off turns prompts back on. The footer always shows the current mode.

At an approval: y approves once, n rejects, a always allows what the prompt describes (for a command, only that exact command) for the rest of the session, v expands a long preview.

For -p runs nobody is there to approve, so actions that would need approval are rejected. Use --mode auto-edit to allow file edits, or --mode full-auto for unattended commands.

For changes made through file tools, the completion report records recognized check commands after the latest edit. passed means those commands exited zero; it does not assess test coverage or prove the change correct. Failed checks are reported, and another edit clears the earlier check results. Unrecognized commands and changes with no checks remain unverified; documentation-only edits do not trigger a test reminder.

Memory

Qriton keeps a memory of your project across sessions: conventions, decisions, facts that were hard to find. Ask it to remember something, or use /remember. Corrections keep the earlier wording, and forgotten facts can be restored.

When a proposed fact matches an existing memory, automatic capture keeps the existing wording if it differs. Agent remember calls also preserve matched user-supplied, pinned or higher-confidence facts; explicit corrections use update_memory under the current approval mode. Agent corrections record the agent as their source. Matching does not detect every contradiction, so review important memories. Forgetting retains history for restoration and is not secure deletion.

/remember prices are integer euro cents, never floats
/memory              what is stored, recent entries
/recall <query>      search memory
/forget <id>         drop a memory (/restore <id> brings it back)
/graph               see your project memory as an interactive graph

/graph, or qriton memory graph from the shell, opens your project's memory in the browser: what qriton knows, how the pieces connect, what was corrected and when. Select a memory to see its history and connections, or to copy the command that forgets or restores it (qriton memory forget <id> works from the shell too). The page itself is a single private file that works offline and cannot change anything. qriton memory graph json, dot or mermaid exports it for other tools.

Memory is stored locally per project. Recalled facts become context for your selected chat model, and semantic recall sends text to the configured embedding service. With the local embedding model installed (qriton pull bge-m3), recall also finds related facts that use different words.

Commands

Type / for suggestions. The most used:

| | | |---|---| | /help | all commands and shortcuts | | /model <name>, /models | switch or browse models | | /mode <mode>, /auto [on\|off] | change approval mode | | /project | current changes, recent work and recorded checks | | /sessions, /resume [id] | browse and continue past conversations | | /memory, /remember, /recall, /forget | project memory | | /hlm | run and edit Qriton HLM models; /hlm overview shows local setup and next steps | | /servers, /server <url> | find or select an Ollama server | | /image <path> | attach a screenshot to your next message | | /compact | summarise the conversation to free space | | /stats, /usage | speed, context use, token and cost log | | /unload | free the memory local models are using | | /theme auto\|light\|dark | colours: auto matches your terminal's background | | /clear | start over |

From the shell: qriton project, qriton hlm, qriton models, qriton sessions, qriton usage, qriton doctor, qriton capabilities.

Configuration

Settings live in ~/.qriton/config.json. A project can add its own .qriton/config.json; for safety, Qriton ignores it until you review and approve it with qriton trust show and qriton trust grant <fingerprint>, and asks again whenever it changes.

{
  "model": "qwen3.5:4b",
  "approvalMode": "suggest",
  "contextTokens": 16384,
  "verifyEdits": true,          // ask the model to test its change before it says it is done
  "fallback": {
    "retries": 3,               // retry a failed request on the same model
    "models": ["qwen3.5:4b"],   // then try these backups, in order
    "switch": "ask"             // "ask" before switching, or "auto"
  }
}

A backup that sends your conversation from a local model to a hosted provider also needs "network": { "allowHostedFallback": true }. In -p runs only "auto" can switch.

| Environment variable | | |---|---| | OLLAMA_HOST | Ollama server (default http://127.0.0.1:11434) | | QRITON_MODEL | model for this run | | ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY | provider keys | | OPENAI_BASE_URL | an OpenAI-compatible server | | TAVILY_API_KEY, BRAVE_API_KEY, SEARXNG_URL | better web search |

Project instructions. Put a QRITON.md in your project root and it is read at the start of every session. AGENTS.md and CLAUDE.md work too.

Several qritons on one network

Qriton instances on different machines can see each other and pass messages, for example asking the one on your Windows box to run the tests there. They meet through a NATS server: any machine on your local network, or a relay on the internet (Azure setup is one option). qriton mesh server prints a ready server configuration that admits your machines.

qriton mesh init nats://10.0.0.5:4222      # first machine: creates a group, prints an invite code
qriton mesh join <code>                    # every other machine

Then set "mesh": { "enabled": true, "name": "laptop" } in ~/.qriton/config.json on each machine. Interactive sessions join the mesh; one-off -p runs stay private. In a session, /peers shows who is online (machine, project, model, busy or idle, and a fingerprint), /tell <peer> <text> sends a message, and /mesh scan finds NATS servers on your network. The model can also list peers and send messages; sending asks for approval unless you run in full-auto.

Mesh messages are end-to-end encrypted. Each machine has its own keys, and every mesh message is encrypted and signed before it leaves, so the NATS server, or anyone on the network, sees only random bytes on random-looking channels. Direct messages can be read by their recipient only, not even by other machines in the group. The invite code contains the group secret, so pass it only over a channel you trust. A relay on the internet also needs tls://, and per-machine keys (qriton mesh status prints the one to add to the server).

A received message is shown to you and waits for /accept. With "accept": "auto" it joins the task queue on its own, so qritons can coordinate work without you in the loop. Either way it is labelled as coming from another agent, never from you: it grants no permission, and every action still goes through your approvals. The mesh is off unless you configure it, and a project can never turn it on.

Incoming messages also pass through the Shield. You always see every message; the Shield only decides whether it may join the task on its own:

• Unflagged messages behave as described above.
• Flagged messages from machines you trust are never held back. List those machines' ids (shown by /peers) in "trusted" in your user config, and the warning travels with the message to you and to the agent. The one exception is a possible credential: it waits for /accept, so a secret never reaches a model without you choosing it.
• Flagged messages from any other member never join by themselves. They wait for /accept, or cannot be accepted at all in Shield block mode or when they contain a possible credential.

Trust is the machine's id, which each message proves with its signature, so a message cannot borrow a trusted machine's name.

Pattern checks can be fooled, so they are not the last line of defence. Once a message from another qriton joins a conversation, trusted or not, that conversation holds outside input, and the status line says so:

• Every action asks you: writes, commands, commits, memory changes and mesh sends, in any approval mode including full-auto.
• Network tools ask too: web search, fetch and research could carry data out in their arguments, so they ask as well.
• No session-wide approvals: "allow for this session" is not offered, and earlier grants do not apply.
• Local reading and thinking stay free: the agent can still read files, reason and draft on its own.

A model that is talked into something by that text still cannot act on it without you. The mark lasts until /clear, because the text stays in the model's context, and a resumed conversation containing such a message is marked again.

A signed agent on the web

Websites are starting to tell known agents from anonymous bots. With Web Bot Auth, the IETF draft that Cloudflare, Google and others are testing, qriton can sign its page fetches (fetch_url, research). A site can then recognise this agent and apply its own policy, instead of blocking it or treating it as a scraper posing as a browser.

qriton agent                          # this agent's key id, and whether signing is on
qriton agent directory ./site         # the public key, ready to host
qriton agent check                    # a signed request to Cloudflare's test endpoint, explained

To turn it on:

1. Host the key directory at an https address you control, at https://agent.example.com/.well-known/http-message-signatures-directory. qriton agent directory writes it, with a web.config for IIS.
2. Set this in ~/.qriton/config.json, listing the sites that should know who you are:

   { "webAgent": { "sign": true, "directory": "https://agent.example.com", "sites": ["shop.example", "*.gov.example"] } }

Page fetches to those sites, over https only, then carry an Ed25519 signature over the target host, valid for one minute, plus a Signature-Agent header pointing at your directory. They identify as qriton/<version> (+https://agent.example.com).

Every other site sees an anonymous browser request, exactly as before. A redirect is decided again for each site it passes through, and a signature never travels on to a site that is not listed. "*" signs everywhere, but only if you write it.

Identifying as an agent also tells a site it may serve you a page written for agents, with hidden instructions. So a page fetched while identified counts as outside input: until /clear, every action in that conversation asks you first. One key can serve several machines: copy ~/.qriton/web-agent.json between them, so sites cannot tell the machines apart.

• The key: it belongs to this installation. It is kept privately in ~/.qriton/web-agent.json, separate from mesh keys; only the public half is published.
• Off by default, and even when on, it only signs for the sites you list.
• User settings only: a project cannot change it.
• Standard format: signatures match the RFC 9421 and draft test vectors, and Cloudflare's test endpoint accepts them as well-formed.
• Recognition: sites recognise the key once the directory is published, and for Cloudflare, once the agent is registered.

Teams and managed machines

Administrators can restrict network destinations, allowed approval modes and which project settings apply, and can run commands in a network-isolated container. For the deployment guide, write to [email protected].

Troubleshooting

• Nothing happens, or the model doesn't load: qriton doctor.
• Slow or out of memory: try qriton --light, a smaller model, or /unload between tasks. Local models are released when Qriton exits.
• A long session runs out of room: /compact summarises it, or raise contextTokens.
• Answers stop mid-way: raise maxOutputTokens.
• Keys: /auth shows which keys are stored; qriton auth <provider> saves one.

Security

Please report vulnerabilities privately to [email protected], not in a public issue. The full policy is in SECURITY.md, included in the package.

License

MIT