zcoder.zsh v0.5.0

zcoder.zsh v0.5.0

v0.5.0 introduces a complete remote-agent architecture, allowing zcoder to run
beside an Ollama model and workspace on another machine while its terminal UI
remains local.

Highlights

Remote-agent server

• Run zcoder headlessly with --server NAME, --port, and --token-file.
• Connect the normal TUI or a one-shot client with --connect HOST.
• Keep model inference, conversation state, workspace access, project guidance,
  Agent Skills, MCP servers, file operations, patches, and shell execution on
  the remote machine.
• Deliver assistant messages, reasoning, tool results, status changes, and turn
  completion as ordered HTTP events.
• Forward exact shell-command approval requests to the local client with
  one-use approval identifiers and a fail-closed timeout.
• Cancel remote turns with Escape and reject overlapping turns with a clear
  busy response.
• Preserve one isolated conversation per named server across process restarts.
• Prevent duplicate processes from claiming the same named server runtime.

Documentation refresh

• Replaced the long, technical root README with a concise project introduction,
  benefit summary, quick start, and documentation map.
• Added focused guides for getting started, the TUI, remote operation, safety,
  project guidance and Skills, MCP, configuration, architecture, and
  development.
• Added explicit token-strength guidance, remote-network warnings, trust
  boundaries, and current remote-mode limitations.

Protocol and safety

• Remote mode requires a shared token of at least 32 URL-safe characters; there
  is no unauthenticated mode.
• The server remains authoritative for its workspace, model, profile, and
  command policy.
• Remote command approval preserves the existing coding and sysadmin policies.
• The server accepts bounded request bodies and keeps runtime files private to
  the current user.

Remote quick start

Create the same private token file on both machines:

umask 077
mkdir -p ~/.config/zcoder
openssl rand -hex 16 > ~/.config/zcoder/remote.token

Start the server on the workspace machine:

./zcoder.zsh \
  --server "Workshop Mac" \
  --port 7337 \
  --token-file ~/.config/zcoder/remote.token \
  --model qwen3-coder \
  --workspace /path/to/project

Connect from the local machine:

./zcoder.zsh \
  --connect workshop-mac.local:7337 \
  --token-file ~/.config/zcoder/remote.token

Read the remote-agent guide for the complete setup.

Security note

The native Zsh TCP listener accepts connections on all interfaces. Remote mode
uses authenticated plain HTTP: the token prevents unauthenticated access but
does not encrypt traffic. Use it only on a trusted LAN protected by firewall
rules, or carry the connection through an SSH or VPN tunnel. Do not expose the
port directly to the internet.

Current limitations

The first remote release supports one active turn and one persistent session per
named server. Remote session browsing and reset, model switching, manual
compaction, management screens, and external consultant commands are not yet
exposed to the client.

Compatibility and verification

• Zsh 5.8 or newer
• Ollama with a tool-capable model
• 462 automated tests passing
• Native TCP smoke checks for authentication, remote turns, and duplicate-server
  locking
• Automated coverage for approval resumption and cancellation

For the full documentation, see the documentation index.