Local Coding AgentRemote Agentv0.6.0Zsh • Ollama • Curses

zcoder.zsh

A capable coding agent for Ollama, built almost entirely in Zsh. Work locally, or run the complete agent beside a remote model and workspace while keeping the focused terminal interface in front of you.

Small enough to inspect: HTTP, JSON, tool dispatch, sessions, and the interface use native Zsh modules. External programs are reserved for the capabilities they actually provide.

Release status: v0.6.0 is the latest published release. The main branch currently identifies itself as v0.6.1 and contains post-release development.

zcoder.zsh terminal interface showing project sessions, the coding profile, available agent tools, shell approval policy, and an agent conversation
The coding workspace at a glance: sessions, project guidance, agent tools, approval policy, model status, and the live transcript.

A Real Agent Loop

zcoder follows a compact observe → decide → act → check cycle. It has no arbitrary model-turn ceiling while progress continues, but detects repeated and alternating tool loops before they become runaway sessions.

Search and bounded file reads

Workspace-confined writes and patches

Approved build and test commands

Agent Skills and project guidance

stdio MCP servers

Persistent local and remote sessions

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.

coding — the default

Searches before reading broadly, works in small verifiable steps, edits only inside the selected workspace, and asks before shell commands run. You may approve one command or the rest of the session.

sysadmin — guarded operations

Begins with read-only diagnosis and requires approval for every exact command. Its prompt emphasizes least privilege, backups, rollback, validation, secret redaction, and extra care around storage, networking, SSH, boot, authentication, and critical services.

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

Safeguards stay in force: sysadmin mode rejects --yes and session-wide approval. Workspace file tools remain confined, host access goes through individually approved commands, and a pre-execution guard rejects unmistakably catastrophic operations.

Safety You Can See

Workspace Boundary

Built-in file tools canonicalize paths and reject anything outside the selected workspace.

Command Approval

Shell commands start in ask mode and remain visible before they run.

Project-aware

Hierarchical AGENTS.md files, Agent Skills, and MCP tools extend the agent without weakening its boundaries.

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.6.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=RemoteHost: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.

Remote Execution

The server owns the model, source tree, agent state, and tool execution—not just the Ollama connection.

Local Control

Prompts, streamed events, command approvals, and Escape-to-cancel remain in your local terminal.

Server-enforced Policy

The remote host fixes the workspace, model, profile, and command policy. A connected client cannot replace them.

# 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

Secure the connection: remote mode uses token-authenticated plain HTTP. Use it on a trusted, firewalled LAN or through an SSH or VPN tunnel—never expose port 7337 directly to the internet.

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.