Agent Mode

Agent mode is ZenCoder's most powerful feature. Give it a natural-language task and it will autonomously read your code, reason about what to change, and apply precise edits — all within your workspace.

⚠️

Agent mode can modify files. Review proposed edits carefully before confirming. Use --max-iter to limit autonomous steps on complex tasks.

How it works

Agent mode uses a ReAct loop — Reason, Act, Observe — until the task is complete or the iteration limit is reached.

1. Plan

ZenCoder reads the task and decides which files to explore first.

2. Read

It calls file_read, file_glob, and workspace_search to gather context.

3. Reason

The model synthesises what it found and decides what edits are needed.

4. Edit

It calls file_edit with a precise diff. You're shown the proposed change and asked to confirm.

5. Verify

It re-reads the edited file to check the change landed correctly.

6. Repeat

If more files need changing, it continues until done or max iterations.

Agent tools

The agent has access to six workspace tools. It decides which to call based on the task.

Tool	Description	Example trigger
file_read	Read the full contents of any file in the workspace	Read internal/server/server.go
file_glob	Find files matching a glob pattern (e.g. */.go)	Find all test files in internal/
workspace_search	Full-text search across the entire workspace	Search for all uses of AppError
list_directory	List directory contents recursively	What's inside internal/llm/?
file_edit	Apply a targeted diff/edit to a file	Add error handling to auth middleware
file_remove	Delete a file from the workspace	Remove the deprecated utils_old.go

CLI usage

Simple agent task

zencoder agent "Add input validation to all POST handlers"

With a specific model and iteration limit

zencoder agent \
  -m anthropic/claude-3-5-sonnet \
  --max-iter 20 \
  -w ./internal \
  "Refactor the auth module to use the new AppError type throughout"

Review the session trace

Each agent step is logged. You'll see something like:

[Agent] Reading: internal/auth/middleware.go
[Agent] Search: "AppError" → 12 matches in 5 files
[Agent] Reading: internal/errors/errors.go
[Agent] Proposing edit to internal/auth/middleware.go

--- a/internal/auth/middleware.go
+++ b/internal/auth/middleware.go
@@ -42,7 +42,7 @@
-    return fmt.Errorf("unauthorized: %v", err)
+    return &AppError{Code: 401, Msg: "unauthorized", Cause: err}

Apply this change? (y/n/skip): y
[Agent] ✓ Applied. Continuing...

Agent mode in VSCode

Switch the Mode dropdown to Agent in the chat panel. All subsequent messages run through the agent loop — ZenCoder will read and edit files in your open workspace directory.

ℹ️

Plan mode shows the proposed step list before executing. Ask mode is single-turn and never edits files. Agent mode is the only mode that can write to disk.

Best practices

·Be specific about scope: 'Refactor the auth module' is better than 'Refactor the codebase'.
·Use --max-iter on large tasks to step through changes incrementally.
·Review each proposed edit before confirming — the agent shows diffs.
·Commit your current work before running agent mode on critical files.
·Use --routing cloud for complex multi-file refactors; local models work for small, targeted edits.
·The agent has no network access — it can only read/write files in your workspace.

Troubleshooting — common issues and fixes