zcoder.zsh

A Real Agent Loop

zcoder follows a compact observe → decide → act → check cycle. It has no arbitrary model-turn ceiling while progress continues. Repeated outcomes and short alternating cycles trigger one final recovery turn; another violating round is stopped before execution.

Call in a Specialist. Keep the Boundaries.

Ask Claude, Codex, Agy, or OpenCode for a second opinion without handing over the workspace. Add ! only when you want one external harness to make a workspace-confined editing pass.

Ready Before You Press Enter

The interactive TUI warms the selected Ollama model with the resolved system prompt and project instructions while you type, showing Warming Up until the model is ready. The disposable request never enters your transcript, saved session, or context ledger—and your first real prompt safely takes priority.

Project-Aware by Default

Hierarchical AGENTS.md files, discoverable Agent Skills, and stdio MCP tools are built in. zcoder reads project guidance and context from the workspace itself, so every run starts aligned with your conventions.

Communication Between Agents

Multiple zcoder instances on the same machine can discover each other via a private Unix socket, pass tasks along, and queue follow-ups for later. You can work with several focused agents without manual handoffs.

One Agent, Two Deliberate Profiles

zcoder does not treat software development and host administration as the same job. The default coding profile is built for project work; --profile sysadmin switches to a dedicated operations prompt and a stricter execution policy.

./zcoder.zsh --profile sysadmin \
  --model qwen3-coder \
  --workspace /path/to/maintenance-workspace

Safety You Can See

Every tool call keeps its own validation, safety guard, approval, result, and error. v0.8.0 ships with 730 automated tests covering external workers, partial writes, private permissions, terminal controls, symlink handling, multi-call execution, patch recovery, and transport replay.

Compile It for a Faster Launch

Run make compile once and zcoder precompiles its Zsh libraries to .zwc wordcode, roughly halving launch time. Zsh automatically uses current wordcode and ignores it when the matching source is newer, so this is a safe, optional speed boost—not a separate build you have to maintain.

make compile   # Generate lib/*.zwc
make clean     # Remove compiled wordcode

Try It Locally

You need Zsh 5.8+, ripgrep, a running Ollama server, and a model with tool-calling support. zcoder uses localhost:11434 by default. Set OLLAMA_HOST or pass --host to use Ollama on another machine. Download v0.18.0 for the released baseline; cloning main follows ongoing development.

ollama pull qwen3-coder
git clone https://github.com/ZaguanLabs/zcoder.zsh.git
cd zcoder.zsh
make compile
./zcoder.zsh --model qwen3-coder \
  --workspace /path/to/project

# Use a remote Ollama server
export OLLAMA_HOST=remote-host:11434
./zcoder.zsh --model qwen3-coder --workspace .

Your Terminal Here. The Agent There.

Start zcoder with --server on the machine that owns the project. The model connection, workspace, conversation, project instructions, Skills, MCP processes, and every tool stay on that host. Connect with --connect and your local zcoder becomes a thin, responsive TUI.

Prompts and streamed events stay in your local TUI, exact command approvals return to you without deadlocking the remote worker, and Escape cancels the active turn. If the server's model was displaced, zcoder reloads it before starting queued work.

# On the remote machine
./zcoder.zsh \
  --server "Workshop Mac" \
  --token-file ~/.config/zcoder/remote.token \
  --model qwen3-coder \
  --workspace /path/to/project

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

This is more than --host, which connects a local zcoder process to a remote Ollama server while keeping the workspace and tools local. Remote-agent mode moves the whole working environment to the server.