ZELL Documentation

Quick start

Zell has no Node or npm runtime requirement. Artifact size and linkage vary by release target; building from source requires zig 0.16+.

# 1. Clone and build (ReleaseSmall keeps it small)
git clone https://github.com/Jackallink/zell && cd zell
zig build -Doptimize=ReleaseSmall
# artifact lands in zig-out/bin/zell
ls -lh zig-out/bin/zell   # measure the target you will ship

First prompt

# DeepSeek (the currently documented public provider)
export DEEPSEEK_API_KEY=sk-...
./zig-out/bin/zell --model deepseek-v4-flash -p "What is 2+2?"

# pick a model / attach file references
./zig-out/bin/zell --model deepseek-v4-flash -p "explain this code" @src/main.zig

# enter the interactive TUI
./zig-out/bin/zell

CLI reference

Usage: zell [flags] [message] [@file …]. With no arguments it enters the interactive TUI; with -p or a mode flag it uses the corresponding output channel.

TUI slash commands

$ zell
───
> Zell | deepseek-chat
───
Welcome to Zell!
Type /help for commands, /quit to exit.

> /help
/help      list commands
/settings  not implemented
/model     show current model (switching not implemented)
/quit      exit (/q)

Four modes

One core, four exits: a human in the terminal, scripts pulling data, CI assertions, IDE embedding. All four modes live in the same binary — no daemon.

JSON mode: event types

$ zell --mode json -p "say hi" | jq -s 'map(.type)'
[
  "zell.protocol","agent_start","message_start","message_end","turn_start",
  "message_start","message_update",…,"message_end","turn_end",
  "agent_end","done"
]

RPC mode: one prompt

$ printf '%s\n' '{"id":"1","command":"prompt","text":"hi"}' | zell --mode rpc
{"type":"zell.protocol","version":1,"capabilities":[…]}
{"type":"response","command":"prompt","success":true,"id":"1"}
{"type":"agent_start","turn":0}
{"type":"message_start","turn":0,"role":"user"}
…event stream…
{"type":"agent_end","turn":1}
{"type":"done","turn":1}

Protocol v1

Version 1: breaking changes bump the version; additive event types do not. Every channel (--mode json / --mode rpc) speaks NDJSON — one JSON object per line, UTF-8. The first line is the zell.protocol handshake; the following agent-event objects carry their turn number.

Event model

Agent events share type (event name), turn (turn number, starting at 0), plus type-specific fields. The handshake and RPC response objects have their own shapes and do not carry turn.

Typical single-turn order

agent_start
message_start(user) message_end(user)
turn_start
message_start(assistant)
message_update ×N
message_end(assistant)
turn_end
agent_end
done

With tools, one turn: after message_end(assistant) and before turn_end, each tool emits one tool_execution_start / tool_execution_end pair. If stop_reason=length (output truncated), tool calls in that turn don't run and are reported with an error result, then a retry turn follows.

Real capture (DeepSeek)

{"type":"zell.protocol","version":1,"capabilities":["tool_execution_update","prepare_next_turn_snapshot","default_parallel","thinking_level","steer_follow_up","structured_session","rpc_continue"]}
{"type":"agent_start","turn":0}
{"type":"message_start","turn":0,"role":"user"}
{"type":"message_end","turn":0,"role":"user"}
{"type":"turn_start","turn":0}
{"type":"message_start","turn":0,"role":"assistant"}
{"type":"message_update","turn":0,"text":"Hi"}
{"type":"message_update","turn":0,"text":" there"}
{"type":"message_update","turn":0,"text":"!"}
…streaming deltas…
{"type":"message_end","turn":0,"role":"assistant"}
{"type":"turn_end","turn":0,"text":"stop"}
{"type":"agent_end","turn":1}
{"type":"done","turn":1}

RPC commands

One command JSON per stdin line; stdout mixes response and events (both NDJSON); id correlates request/response (optional).

Sessions & resume

Sessions persist as structured message JSONL at .zell/sessions/<id>.jsonl. -c / --continue restores the selected session as provider history; --name selects its id.

$ zell --name oncall -p "continue the last fix"
$ zell --name oncall -c -p "push one more layer"
$ ls .zell/sessions/
oncall.jsonl  proto1.jsonl  demo1.jsonl  c13.jsonl  …
$ head -3 .zell/sessions/proto1.jsonl
{"role":"user","content":"continue the last fix"}
{"role":"assistant","content":"…"}
{"role":"tool","content":"…","tool_call_id":"call_0","is_error":false}

A session file is not the protocol event stream and is not an immutable audit log. It is a local conversation record used for resume.

Security

The current Zell baseline is a local host tool: it runs with the invoking user's authority. It is not a sandbox, a secret-isolation mechanism, or a hardened filesystem boundary.

• The current bash tool has host process, filesystem, and network authority; it is not confined.
• A child shell can inherit the host environment. Environment/CLI key input is configuration, not a key-isolation guarantee.
• No built-in MCP is a product-surface choice, not a sandbox boundary.
• A small binary can reduce dependencies, but it does not replace authorization or OS enforcement.
• Session JSONL is an operational conversation record, not tamper-proof or immutable audit evidence.

Principles

Zell is a minimal coding-agent harness implemented in Zig. Public documentation distinguishes verified behavior from planned work and states security boundaries explicitly.